🖥️ Manage Space secrets and variables from the CLI

You can now manage Space secrets and environment variables directly from the command line with two new hf spaces subgroups: secrets and variables. Use hf spaces secrets to add, list, and delete write-only secrets, and hf spaces variables to add, list, and delete readable environment variables. Both add commands support multiple -s/-e flags and --secrets-file/-env-file for loading from dotenv files. On the Python side, HfApi.get_space_secrets() returns secret metadata (key, description, updated timestamp) without ever revealing values.

# List secrets (values are write-only — only keys and timestamps are shown)
$ hf spaces secrets ls username/my-space

# Add secrets
$ hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...
$ hf spaces secrets add username/my-space --secrets-file .env.secrets

# Delete a secret (confirmation prompt, use --yes to skip)
$ hf spaces secrets delete username/my-space OPENAI_API_KEY --yes

# List, add, and delete variables (values are readable)
$ hf spaces variables ls username/my-space
$ hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512
$ hf spaces variables delete username/my-space MAX_TOKENS --yes

• [CLI] Add hf spaces secrets and variables subgroups by @davanstrien in #4170
• [CLI] Add get_space_secrets + hf spaces secrets ls by @Wauplin in #4182

📚 Documentation: CLI guide · Manage your Space

🪣 Rsync-style trailing slash for bucket folder copies

hf buckets cp now supports rsync-style trailing slash semantics when copying folders. A trailing / on the source path copies only the folder's contents to the destination, while omitting it nests the folder itself — matching the behavior you'd expect from rsync. This makes it possible to flatten directory structures during copies, which was not possible before. Additionally, copy_files now raises an explicit EntryNotFoundError when the source path resolves to no files, instead of silently succeeding with zero operations.

# Without trailing slash: "logs" dir is nested => dst/logs/...
$ hf buckets cp hf://buckets/username/src-bucket/logs hf://buckets/username/dst/

# With trailing slash: only contents of "logs" are copied => dst/...
$ hf buckets cp hf://buckets/username/src-bucket/logs/ hf://buckets/username/dst/

• [Buckets] Support rsync-style trailing slash in copy_files by @Wauplin in #4187
• [CLI] Raise error when copy_files source doesn't exist by @Wauplin in #4186

📚 Documentation: Buckets guide · CLI guide

💔 Breaking Change

• [CLI] Rename hf skills upgrade -> hf skills update by @hanouticelina in #4176 — hf skills upgrade no longer exists; use hf skills update instead.
• [CLI] Add out.status() by @hanouticelina in #4171 — status updates (spinners/progress) on hf extensions install and hf spaces dev-mode are now suppressed when using --format json, --quiet, or --format agent.

🖥️ CLI

• [CLI] Add hints and example to hf datasets leaderboard by @Wauplin in #4174
• [CLI] Shortcut hf update when already on latest version by @julien-c in #4177
• [CLI] Remove progress bars on skills update by @Wauplin in #4179
• [CLI] Increase default --limit from 10 to 30 for list commands by @Wauplin in #4181
• [CLI] Support hf -v to print version by @Wauplin in #4185
• [CLI] migrate hf skills to bucket by @hanouticelina in #4175

🐛 Bug and typo fixes

• Update typer dependency version in setup.py by @tomaarsen in #4193

🏗️ Internal

• Post-release: bump version to 1.14.0.dev0 by @huggingface-hub-bot[bot] in #4172
• [Release] Move social drafts to minor-release and archive release notes to bucket by @Wauplin in #4173
• Update unit test warnings check to ignore unrelated deprecation warnings by @seanses in #4188
• [internal] Untrack useless files by @Wauplin in #4191

🖥️ New CLI commands: repo cards, file listings, and dataset leaderboards

This release adds three new CLI capabilities for exploring Hub content. hf models card, hf datasets card, and hf spaces card fetch the README of any repo and print it to stdout, with --metadata (YAML frontmatter as JSON) and --text (prose only) flags for splitting the card into its structured and unstructured parts. Calling hf models ls <repo_id>, hf datasets ls <repo_id>, or hf spaces ls <repo_id> now switches from listing repos to listing files inside that repo, with --tree, -R, -h, and --revision options mirroring the existing hf buckets ls behavior. And hf datasets leaderboard <dataset_id> surfaces model scores submitted to a benchmark dataset, making it easy to compare models by score from the terminal.

# Get model card metadata as JSON
hf models card google/gemma-4-31B-it --metadata --format json

# List files in a model repo (tree view with sizes)
hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h

# Show top 5 models on SWE-bench
hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5

📚 Documentation: CLI guide

• [CLI] Add hf models card and hf datasets card commands by @davanstrien in #4118
• [CLI] Add file listing to models/datasets/spaces ls by @Wauplin in #4166
• [CLI] add hf datasets leaderboard by @hanouticelina in #4154

🚀 Manage Spaces from the CLI

Three new hf spaces subcommands bring full lifecycle control to the terminal. hf spaces pause and hf spaces restart stop or rebuild a Space (with --factory-reboot for a clean rebuild), and hf spaces settings lets you configure sleep time and hardware in one call. A companion hf spaces hardware command lists all available hardware flavors with pricing, so you can discover options before changing settings. Pause and restart include a confirmation prompt (-y to skip) since they tear down the running container.

# Pause a Space when not in use (not billed while paused)
hf spaces pause username/my-space

# Restart with a GPU
hf spaces settings username/my-space --hardware t4-medium --sleep-time 3600

# List available hardware options
hf spaces hardware

📚 Documentation: CLI guide — Spaces

• [CLI] Add spaces lifecycle commands: pause, restart, sleep by @davanstrien in #4155
• [CLI] Add hf spaces hardware command by @Wauplin in #4169
• [CLI] Add --hardware flag to hf spaces settings by @davanstrien in #4163

🔃 hf update replaces the auto-update prompt

The blocking interactive Y/n auto-update prompt at CLI startup is gone. It was catching too many non-interactive contexts (CI runners, Homebrew post-install hooks, Jupyter notebooks) and hanging automation. In its place, a single yellow stderr warning suggests running hf update — a new command that detects how hf was installed (Homebrew, standalone installer, or pip) and runs the right upgrade command. Set HF_HUB_DISABLE_UPDATE_CHECK=1 to silence the startup check entirely, for example in offline CI.

hf update

📚 Documentation: CLI guide — Updating

• [CLI] Add hf update + drop interactive update prompt by @Wauplin in #4131

✏️ Global output formatting for every command

The --format, --json, and -q / --quiet flags are now handled globally by the CLI framework instead of being declared individually on each command. This means every hf command automatically accepts them — no more per-command --format boilerplate, and the flags are properly documented in a dedicated "Formatting options" section in every --help page. --format auto (the default) picks human for interactive terminals and agent when invoked by an AI agent, making CLI output automatically suitable for both people and tools.

# JSON output for scripting
hf models ls --search bert --limit 2 --json | jq '.[].id'

# IDs only, one per line
hf collections ls --owner nvidia -q

📚 Documentation: CLI guide — Output formatting

• [CLI] Make --format / --json / -q global by @Wauplin in #4162

🔗 Centralized hf:// URI parsing

A new parse_hf_uri function and HfUri dataclass provide a single source of truth for parsing hf://... strings across the library. Whether you reference a model, dataset, space, bucket, or file inside a repo, the parser handles all valid URI shapes — type prefixes, revisions, and paths — and rejects invalid ones with clear error messages. A companion parse_hf_mount / HfMount handles volume mount specifications (hf://...:/mnt:ro). Both are pure string parsers (no network calls) and round-trippable via .to_uri().

from huggingface_hub import parse_hf_uri, parse_hf_mount

parse_hf_uri("hf://datasets/namespace/my-dataset@refs/pr/3/train.json")
# HfUri(type='dataset', id='namespace/my-dataset', revision='refs/pr/3', path_in_repo='train.json')

parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:ro")
# HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', ...), mount_path='/mnt', read_only=True)

📚 Documentation: HF URIs reference

• Centralize hf:// URI parsing by @Wauplin in #4158

🚀 Bucket transport for Jobs script upload

Local scripts uploaded by hf jobs uv run are now stored in a {namespace}/jobs-artifacts bucket and mounted into the job container at /data instead of being base64-encoded into an environment variable. The old bash -c + xargs + base64 -d pipeline was fragile and required manual shell quoting. Bucket transport is simpler, easier to debug, and supports write-back: jobs can persist output artifacts to /data/ since the mount is read-write. The base64 transport path has been fully removed with no fallback.

• Add bucket+mount transport for Jobs script upload by @davanstrien in #4025

🖥️ CLI

• [CLI] Print help when leaf command with required args is called without args by @Wauplin in #4135

🤖 Inference

• [Inference Providers] Add DeepInfra support by @hanouticelina in #4114
• Support list[str] inputs in feature_extraction by @SJeffZhang in #4115

📖 Documentation

• [CLI] Add benchmark dataset filter examples by @hanouticelina in #4156

🐛 Bug and typo fixes

• [BUG FIX]: hf_hub_download crashes when stderr lacks a real file descriptor by @tobocop2 in #4065
• [CLI] Fix datasets list table rendering by @hanouticelina in #4157
• [CLI] Fix installation method detection for curl-installed hf with Homebrew Python by @Wauplin in #4142
• Avoid reuploading preuploaded LFS files in upload-large-folder by @Dev-Jahn in #4165

🏗️ Internal

• [Release] Make release-notes job fail loudly on bad model/empty output by @Wauplin in #4138
• [Release] Fix bucket URL in social posts Slack notification by @Wauplin in #4139
• Post-release: bump version to 1.13.0.dev0 by @huggingface-hub-bot[bot] in #4140
• [CI] Fix two flaky Windows tests (root causes, not skips) by @Wauplin in #4141
• [Quality] Fix uvx ty check src errors by @Wauplin in #4159
• [Release] Mark minor releases as "latest" on GitHub by @Wauplin in #4167

• [Inference Providers] Add DeepInfra support in #4114 by @hanouticelina

Full Changelog: v1.12.1...v1.12.2

🖥️ Unified output format for hf buckets commands

All hf buckets commands now use the unified --format [auto|human|agent|json|quiet] flag and the out singleton for consistent, scriptable output. The previous --quiet and --format table|json flags have been replaced by a single --format option that works across create, list, info, delete, rm, move, and cp. Success messages use out.result(), detail views use out.dict(), and listings use out.table() with proper empty-results handling — making the buckets CLI consistent with the rest of the hf command suite.

# Quiet mode: print only bucket IDs
hf buckets list --format quiet

# JSON output for scripting
hf buckets create my-bucket --format json

# Agent-friendly structured output
hf buckets info username/my-bucket --format agent

• [CLI] Migrate buckets commands to out singleton by @hanouticelina in #4111

📚 Documentation: Buckets guide · CLI guide

🪣 Search buckets by name

You can now filter buckets by name when listing them, both from the Python API and the CLI. Pass search="checkpoint" to list_buckets() or --search "checkpoint" to hf buckets list to find buckets matching a name pattern, without having to list and filter client-side.

# Filter buckets by name
hf buckets list --search "checkpoint"

# Filter buckets by name in Python
for bucket in list_buckets(search="checkpoint"):
    print(bucket.id)

• [Buckets] Add search param to list_buckets by @alexpouliquen in #4130

📚 Documentation: Buckets guide · CLI guide

🖥️ CLI

• [CLI] spaces hot-reload: misc improvements by @cbensimon in #4049
• [CLI] Detect pi agent by @hanouticelina in #4125

🐛 Bug and typo fixes

• Apply fsspec config in HfFileSystem metaclass by @joaquinhuigomez in #4062

🔧 Other QoL Improvements

• [Buckets] Skip local walk for download sync without delete by @abidlabs in #4123
• [HfApi] Add mainSize to ExpandDatasetProperty_T by @Wauplin in #4136

🏗️ Internal

• [Internal] Fix slack-message draft release permissions + update model by @hanouticelina in #4119
• Post-release: bump version to 1.12.0.dev0 by @huggingface-hub-bot[bot] in #4120
• [Internal] Make RELEASE_NOTES_MODEL configurable via repo variable by @Wauplin in #4126
• [Release] Add social media draft generation to release workflow by @Wauplin in #4132
• chore: bump doc-builder SHA for main doc build workflow by @rtrompier in #4137
• [Release] Make release-notes job fail loudly on bad model/empty output by @Wauplin in #4138

🔍 Semantic search for Spaces

Discover Spaces using natural language. The new search_spaces() API and hf spaces search CLI use embedding-based semantic search to find relevant Spaces based on what they do - not just keyword matching on their name.

>>> from huggingface_hub import search_spaces

>>> results = search_spaces("remove background from photo")
>>> for space in results:
...     print(f"{space.id} (score: {space.score:.2f})")
briaai/BRIA-RMBG-1.4 (score: 0.87)

The same capability is available in the CLI:

$ hf spaces search "remove background from photo" --limit 3
ID                           TITLE                 SDK    LIKES STAGE   CATEGORY           SCORE
---------------------------- --------------------- ------ ----- ------- ------------------ -----
not-lain/background-removal  Background Removal    gradio 2794  RUNNING Image Editing      0.85 
briaai/BRIA-RMBG-2.0         BRIA RMBG 2.0         gradio 918   RUNNING Background Removal 0.84 
Xenova/remove-background-web Remove Background Web static 739   RUNNING Background Removal 0.81 
Hint: Use --description to show AI-generated descriptions.

# Filter by SDK, get JSON with descriptions
$ hf spaces search "chatbot" --sdk gradio --description --json --limit 1 | jq
[
  {
    "id": "BarBar288/Chatbot",
    "title": "Chatbot",
    "sdk": "gradio",
    "likes": 4,
    "stage": "RUNNING",
    "category": "Other",
    "score": 0.5,
    "description": "Perform various AI tasks like chat, image generation, and text-to-speech"
  }
]

• Add hf spaces command with semantic search by @Wauplin in #4094

📜 Programmatic access to Space logs

When a Space fails to build or crashes at runtime, you can now retrieve the logs programmatically — no need to open the browser. This is particularly useful for agentic workflows that need to debug Space failures autonomously.

>>> from huggingface_hub import fetch_space_logs

# Run logs (default)
>>> for line in fetch_space_logs("username/my-space"):
...     print(line, end="")

# Build logs — for BUILD_ERROR debugging
>>> for line in fetch_space_logs("username/my-space", build=True):
...     print(line, end="")

# Stream in real time
>>> for line in fetch_space_logs("username/my-space", follow=True):
...     print(line, end="")

The CLI equivalent:

$ hf spaces logs username/my-space              # run logs
$ hf spaces logs username/my-space --build      # build logs
$ hf spaces logs username/my-space -f           # stream in real time
$ hf spaces logs username/my-space -n 50        # last 50 lines

• Add fetch_space_logs + hf spaces logs command by @davanstrien in #4091

🖥️ CLI output standardization continues

This release continues the CLI output migration started in v1.9, bringing 11 more command groups to the unified --format flag. The old --quiet flags on migrated commands are replaced by --format quiet.

$ hf cache ls                          # auto-detect (human or agent)
$ hf cache ls --format json            # structured JSON
$ hf cache ls --format quiet           # minimal output, great for piping
$ hf upload my-model . .               # auto-detect (human or agent)

Confirmation prompts (e.g., hf cache rm, hf repos delete, hf buckets delete) are now mode-aware: they prompt in human mode, and require --yes in agent/json/quiet modes - no more hanging scripts.

Commands migrated in this release: collections, discussions, extensions, endpoints, webhooks, cache, repos, repo-files, download, upload, and upload-large-folder. Remaining commands (jobs, buckets, auth login/logout) will follow in a future release.

• Migrate collections, discussions, extensions, endpoints and webhooks to out singleton by @hanouticelina in #4057
• Migrate hf cache to out singleton by @hanouticelina in #4070
• Add out.confirm() and migrate all confirmation prompts by @hanouticelina in #4083
• Migrate repos and repo-files to out singleton + add confirmation to hf repos delete by @hanouticelina in #4097
• Migrate download, upload, upload-large-folder to out singleton by @hanouticelina in #4100

📦 Space volumes management from the CLI

A new hf spaces volumes command group lets you manage volumes mounted in Spaces directly from the command line — list, set, and delete using the familiar -v/--volume syntax.

# List mounted volumes
$ hf spaces volumes ls username/my-space
TYPE    SOURCE                MOUNT_PATH READ_ONLY
------- --------------------- ---------- ---------
model   gpt2                  /data      ✔
dataset badlogicgames/pi-mono /data2     ✔

# Set volumes
$ hf spaces volumes set username/my-space -v hf://buckets/username/my-bucket:/data
$ hf spaces volumes set username/my-space -v hf://models/username/my-model:/models

# Delete all volumes
$ hf spaces volumes delete username/my-space

• Add hf spaces volumes commands by @Wauplin in #4109

🔧 More CLI improvements

hf auth token - Prints the current token to stdout, handy for piping into other commands:

$ hf auth token
hf_xxxx
Hint: Run `hf auth whoami` to see which account this token belongs to.

# Use it in a curl call
$ hf auth token | xargs -I {} curl -H "Authorization: Bearer {}" https://huggingface.co/api/whoami-v2

• Add hf auth token command by @Wauplin in #4104

💔 Breaking change

model_name deprecated in list_models - Use search instead. Both were always equivalent (both map to ?search=... in the API), but now model_name emits a deprecation warning. Removal is planned for 2.0.

# Before
>>> list_models(model_name="gemma")

# After
>>> list_models(search="gemma")

The CLI is not affected - hf models ls already uses --search.

• Deprecate model_name in favor of search in list_models by @Wauplin in #4112

🔧 Other improvements

• Support kernels in list_liked_repos by @Wauplin in #4078

🐛 Bug fixes

• Fix copy file to folder by @Wauplin in #4075
• Match Unix cp -r nesting semantics in copy_files by @Wauplin in #4081
• Ignore .gitattributes when copying repo files to a bucket by @Wauplin in #4082
• Fix reference cycle in hf_raise_for_status causing delayed object destruction by @Wauplin in #4092
• Fix repo delete tests missing --yes flag by @hanouticelina in #4101

📖 Documentation

• Update copy files CLI docs by @Wauplin in #4095
• Fix copy files docs by @Wauplin in #4096
• Give manage-spaces walkthrough steps real headings by @davanstrien in #4108
• Clarify that -v/--volume accepts multiple volumes by @davanstrien in #4113

🏗️ Internal

• [CI] Fix Opencode checksum validation by @Wauplin in #4073
• Post-release: bump version to 1.11.0.dev0 by @huggingface-hub-bot[bot] in #4074
• [Release] Notify PRs included in a release by @Wauplin in #4077
• Update staging CI user by @Wauplin in #4093
• Remove unused inputs from release workflow by @Wauplin in #4098
• Bump doc-builder SHA for PR upload workflow by @rtrompier in #4103
• [Internal] Update AGENTS.md by @Wauplin in #4110

• Fix reference cycle in hf_raise_for_status causing delayed object destruction by @Wauplin in #4092

Full Changelog: v1.10.1...v1.10.2

• Fix copy file to folder (#4075)
• [CLI ]Improving a bit hf CLI discoverability (#4079)
• Support kernels in list_liked_repos (#4078)

Full Changelog: v1.10.0...v1.10.1

📁 Instant file copy between Buckets and Repositories

This release introduces server-side file copy operations that let you move data between Hugging Face storage without downloading and re-uploading. You can now copy files from one Bucket to another, from a repository (model, dataset, or Space) to a Bucket, or between Buckets — all without bandwidth costs. Files tracked with Xet are copied directly by hash (no data transfer), while small text files not tracked with Xet are automatically downloaded and re-uploaded.

>>> from huggingface_hub import copy_files

# Bucket to bucket (same or different bucket)
>>> copy_files(
...     "hf://buckets/username/source-bucket/checkpoints/model.safetensors",
...     "hf://buckets/username/destination-bucket/archive/model.safetensors",
... )

# Repo to bucket
>>> copy_files(
...     "hf://datasets/username/my-dataset/processed/",
...     "hf://buckets/username/my-bucket/datasets/processed/",
... )

The same capability is available in the CLI:

# Bucket to bucket
>>> hf buckets cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archives/logs/

# Repo to bucket
>>> hf buckets cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/

Note that copying files from a Bucket to a Repository is not yet supported.

📚 Documentation: Buckets guide

• HfApi.copy_files method to copy files remotely and update 'hf buckets cp' by @Wauplin in #3874
• Add bucket to collection by @coyotte508 in #4041

⚛️ Introducing Kernel repositories

The Hub now supports a new kernel repository type for hosting compute kernels. This release adds first-class (but explicitly limited) support for interacting with kernel repos via the Python API. Only a subset of methods are officially supported: kernel_info, hf_hub_download, snapshot_download, list_repo_refs, list_repo_files, and list_repo_tree. Creation and deletion are also supported but restricted to a small subset of allowed users and organizations on the Hub.

>>> from huggingface_hub import kernel_info
>>> kernel_info("kernels-community/yoso")
KernelInfo(id='kernels-community/yoso', author='kernels-community', downloads=0, gated=False, last_modified=datetime.datetime(2026, 4, 3, 22, 27, 25, tzinfo=datetime.timezone.utc), likes=0, private=False)

📚 Documentation: Repository guide

• [Kernels] Minimal kernel repo type support (create/delete, download files, list refs/files/tree) by @drbh in #4068

📖 Documentation

• [Docs] Fix outdated docs by @hanouticelina in #4055

🐛 Bug and typo fixes

• Fix custom tqdm_class silently broken in non-TTY environments by @hanouticelina in #4056
• Fix set_space_volumes sending bare array instead of object by @davanstrien in #4054
• Fix set_space_volume / delete_space_volume return types by @abidlabs in #4061

🏗️ Internal

• [CI] Slack-message reads draft release from GitHub directly by @Wauplin in #4044
• [CI] Fix upgrading release notes to latest release by @Wauplin in #4045
• Add live Slack notifications to release workflow by @Wauplin in #4046
• Post-release: bump version to 1.10.0.dev0 by @huggingface-hub-bot[bot] in #4047
• skills publish script run in action to sync up descriptions etc. by @evalstate in #4048
• [CI] Harden release workflow permissions and inputs by @Wauplin in #4072
• [CI] Fix Opencode checksum validation by @Wauplin in #4073

• Fix set_space_volume / delete_space_volume return types #4061 by @abidlabs @Wauplin

Full Changelog: v1.9.1...v1.9.2

• Fix set_space_volumes sending bare array instead of object #4054 by @davanstrien

Full Changelog: v1.9.0...v1.9.1