---
schema_version: 1
route: /t/hf.md
tool: "hf"
---

# sincecutoff.com /t/hf — Hugging Face CLI

- name: Hugging Face CLI
- kind: cli
- children: none
- homepage: <https://huggingface.co/docs/huggingface_hub/guides/cli>

Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows.
Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json).
To stay current, read the changes feed: [`/v1/changes.md?tool=hf`](https://sincecutoff.com/v1/changes.md?tool=hf) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt).

### hf jobs stats and fetch_job_metrics return a snapshot by default (2026-10-08)
- slug: hf-jobs-stats-and-fetch-job-metrics-return-a-snapshot-by-default-276e8cff527d
- score: 0.98

How to use it:

For a running job, use `hf jobs stats <job-id>` or `fetch_job_metrics(job_id=..., follow=False)` to read the current metrics sample and return without waiting. Add `-f/--follow` or `follow=True` to stream until the job completes.

Examples:

```
hf jobs stats <job-id>
```

```
hf jobs stats --format json <job-id>
```

```
from huggingface_hub import fetch_job_metrics
for metrics in fetch_job_metrics(job_id="<job-id>", follow=False):
    print(metrics)
```

- why_it_matters: Read metrics for a running job in a script or coding-agent workflow without waiting for the job to finish.
- before: `hf jobs stats` and `HfApi.fetch_job_metrics` streamed metrics until the job finished, so callers of a running job could wait until their own timeout.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v2.2.0>, <https://github.com/huggingface/huggingface_hub/pull/5091>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md>, <https://huggingface.co/docs/huggingface_hub/v2.1.1/en/package_reference/hf_api>
- gotchas: "Version: v2.2.0"; "JOB_IDS: One or more job IDs; the CLI docs also allow `namespace/job_id`."; "-f, --follow: Stream live stats until the jobs complete; without it, print one snapshot."; "--format: The v2.2.0 release lists `json`, `agent`, and `quiet` for raw API metrics in snapshot output."; "job_id (required): The job ID for `fetch_job_metrics`."; "follow: Defaults to `False` and returns the current sample; `True` streams until the job completes, according to the v2.2.0 release."; "Snapshot output prints the latest sample of each job once and exits."; "Pass `follow=True` or use `-f/--follow` to stream until the job completes."; "Docs conflict: The current CLI reference documents `-f/--follow` and snapshot output but does not list `--format` under `hf jobs stats`; the v2.2.0 release explicitly says snapshot output supports `--format json|agent|quiet`. https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md"

### hf jobs run adds retries, rerun, schedule rescheduling, and port exposure (2026-10-01)
- slug: hf-jobs-run-adds-retries-rerun-schedule-rescheduling-and-port-exposure-93eaab111f1e
- score: 0.98

How to use it:

When maintaining a Hugging Face Job workflow, use `--attempts` to retry failures, `hf jobs rerun` to create a fresh Job from a saved spec, and `hf jobs scheduled reschedule` to change a schedule. Use `hf jobs expose` to replace exposed ports on a running Job.

Examples:

```
hf jobs run --attempts 3 --detach python:3.12 python train.py
```

```
hf jobs rerun <job_id>
```

```
hf jobs scheduled reschedule <scheduled_job_id> "0 9 * * 1"
 hf jobs expose <job_id> 8000 --public 9000
```

- why_it_matters: When maintaining a Hugging Face Job workflow, retry failed jobs, rerun saved job specifications, reschedule scheduled jobs, or expose job ports.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v2.1.0>, <https://huggingface.co/docs/huggingface_hub/v2.1.1/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/main/en/guides/jobs>, <https://huggingface.co/docs/huggingface_hub/v2.2.0/guides/cli>, <https://huggingface.co/docs/huggingface_hub/v2.2.0.rc0/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/v2.2.0/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/v2.1.1/en/guides/jobs>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/jobs.md>, <https://huggingface.co/docs/hub/jobs-configuration>
- gotchas: "Version: v2.1.0"; "--attempts <n>: Maximum attempts, including the first run; defaults to 1. `3` allows two retries."; "--detach: Run the Job in the background and print its ID."; "JOB_ID (required): Job ID to rerun or expose ports for."; "SCHEDULED_JOB_ID (required): Scheduled Job ID to reschedule."; "SCHEDULE (required): Cron expression or supported preset such as `@daily` or `@hourly`."; "PORTS: Positional ports to expose with token-protected access; omitted ports are closed when replacing the configuration."; "--public INTEGER: Expose a port without authentication; repeat for multiple ports. May be combined with positional token-protected ports."; "--clear: Close all exposed ports."; "Prerequisite: The machine must be logged in to Hugging Face; Jobs require a positive credit balance."; "Prerequisite: Manage only Jobs you own or Jobs in organizations where you have write permission."; "Prerequisite: Accessing token-protected exposed ports requires an HF token with read access to the Job's namespace."; "Retries are automatic on failure."; "A rerun starts a fresh Job using an existing Job's saved spec, including secrets and hardware settings."; "Scheduled Jobs can change their cron expression or preset without being recreated."; "Port exposure may be configured at Job creation time or on a running Job."; "`expose` provides token-protected access; `expose_public` provides unauthenticated access."

### hf spaces zero-gpu-quota reports ZeroGPU usage (2026-10-01)
- slug: hf-spaces-zero-gpu-quota-reports-zerogpu-usage-49e4209bba24
- score: 0.96

How to use it:

Before calling ZeroGPU Spaces, check the remaining quota and reset time with `hf spaces zero-gpu-quota`.

- why_it_matters: When building or maintaining a script that calls ZeroGPU Spaces, check the remaining quota and reset time before making calls.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v2.1.0>, <https://github.com/huggingface/huggingface_hub/pull/5040>, <https://huggingface.co/docs/huggingface_hub/v2.1.0/guides/cli>, <https://huggingface.co/docs/huggingface_hub/v2.1.0/en/guides/manage-spaces>
- gotchas: "Version: v2.1.0"; "--format json: Print quota results as JSON."; "Prerequisite: A fine-grained token must have the “Billing > Read billing usage and payment method status” permission."; "Quota values are expressed in GPU-seconds."; "`resets_at` is `None` if ZeroGPU has not been used since the last reset."; "A fine-grained token requires the \"Billing > Read billing usage and payment method status\" permission."; "The CLI prints a credit-purchase hint when less than 10% of the quota is left; the linked documentation says PRO, Team, and Enterprise users can purchase credits to continue beyond the daily quota."; "Docs conflict: The v2.1.0 CLI documentation shows `hf spaces zero-gpu quota` and its `--format json` form, while the release note names `hf spaces zero-gpu-quota`. The documentation does not confirm the release-note command spelling."

### hf webhooks create --watch accepts bucket (2026-09-24)
- slug: hf-webhooks-create-watch-accepts-bucket-750f0da3dec0
- score: 0.93

How to use it:

When configuring an `hf` webhook to watch bucket items, pass `bucket:<owner>/<bucket>` to `--watch`.

Examples:

```
hf webhooks create --url <url> --watch bucket:<owner>/<bucket>
```

- why_it_matters: Configure an `hf` webhook to watch bucket items.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.33.0>, <https://huggingface.co/docs/huggingface_hub/v1.33.0/package_reference/cli>
- gotchas: "Version: v1.33.0"; "--watch TEXT (required): Watched item in `type:name` format; repeatable. Use `bucket:<owner>/<bucket>` for a bucket."; "--url TEXT: URL to send webhook payloads to; provide this or `--job-id`, but not both."; "--job-id TEXT: Job ID to trigger instead of sending payloads to a URL; mutually exclusive with `--url`."; "--domain [repo|discussions]: Repeatable domain filter; defaults to all domains."; "--secret TEXT: Optional secret used to sign webhook payloads."; "--token TEXT: User Access Token for authentication."; "Prerequisite: A User Access Token is available for authentication; the CLI documents `--token` and links to token generation in settings."

### hf cache rm removes an individual cached file (2026-09-17)
- slug: hf-cache-rm-removes-an-individual-cached-file-1ab2da19fe7e
- score: 0.98

How to use it:

When you need to remove one exact cached file while keeping the repo cache usable, pass its `hf://` file URI to `hf cache rm`; it removes that file from every cached revision and deletes its blob only when no other cached file references it. The path must be exact, and file targets cannot be mixed with repository or revision targets.

Examples:

```
hf cache rm hf://models/<owner>/<repo>/<exact-file-path> --dry-run
```

- why_it_matters: Remove one cached file such as a GGUF quantization while keeping the rest of its repository cache usable.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.32.0>, <https://github.com/huggingface/huggingface_hub/pull/4847>, <https://huggingface.co/docs/huggingface_hub/v1.32.0/guides/manage-cache>, <https://huggingface.co/docs/huggingface_hub/package_reference/cli>
- gotchas: "Version: v1.32.0"; "TARGETS... (required): One or more repo IDs, `hf://` URIs, or revision hashes to delete; for this task, use one exact `hf://` file URI."; "--dry-run: Preview deletions without removing anything."; "--cache-dir TEXT: Cache directory to scan; defaults to the Hugging Face cache."; "-y, --yes: Skip the confirmation prompt."; "Paths must match exactly; folders and glob patterns are not supported."; "File targets cannot be mixed with repositories or revisions in the same call."; "`@revision` in `hf://` URIs is rejected."; "Refs and snapshot folders are kept."; "A deleted file is downloaded again the next time it is needed."

### hf jobs uv run reads launch config from UV scripts (2026-09-17)
- slug: hf-jobs-uv-run-reads-launch-config-from-uv-scripts-27deeb19bc38
- score: 0.97

How to use it:

When a UV script needs a specific runtime or launch configuration, declare optional settings in its PEP 723 `[tool.hf-jobs]` table and run `hf jobs uv run <script>`. Script values act as defaults; CLI flags override them, while `env`, `secrets`, `labels`, and `volumes` merge entry by entry.

Examples:

```
hf jobs uv run <script.py>
```

```
# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# image = "vllm/vllm-openai:unlimited-ocr"
# flavor = "l4x1"
# python = "/usr/bin/python3"
# secrets = ["HF_TOKEN"]
# ///
hf jobs uv run <script.py>
```

- why_it_matters: Run a UV script as a Job with its runtime and launch settings declared in the script.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.32.0>, <https://huggingface.co/docs/hub/jobs-configuration>, <https://huggingface.co/docs/huggingface_hub/package_reference/cli>
- gotchas: "Version: v1.32.0"; "SCRIPT (required): Local UV script or URL to run."; "image: Docker image; use an image with `uv` installed."; "flavor: Hardware flavor for the job."; "python: Python interpreter for the run environment."; "timeout: Job timeout; documented examples accept seconds or time units such as `2h`."; "name: Job name, stored as the `name` label."; "namespace: Namespace under which the job runs."; "env: Environment variables; CLI `-e`/`--env` accepts `NAME=value`. Entries merge with CLI entries."; "secrets: Secret names; values are read from the local environment. An unset secret is an error. Entries merge with CLI entries."; "labels: Job metadata labels; docs allow label or `key=value` forms. Entries merge with CLI entries."; "volumes: Job volumes; entries merge with CLI entries."; "network_group: Join a network group; group names allow lowercase letters, digits, and dashes, up to 46 characters."; "network_aliases: Aliases for jobs in a network group; aliases allow lowercase letters, digits, and dashes, up to 34 characters, and must be unique per job."; "Prerequisite: Be authenticated with `hf auth login` using a token permitted to start and manage Jobs; Jobs require a positive credit balance."; "Typos and unknown keys are rejected with the list of valid options."; "Each run prints a config summary with script-sourced values marked and secrets redacted."; "The table is read by the CLI only; `run_uv_job()` and `create_scheduled_uv_job()` ignore it."

### hf sandbox exec keeps secret values out of argv (2026-09-17)
- slug: hf-sandbox-exec-keeps-secret-values-out-of-argv-a713aa1e19be
- score: 0.90

How to use it:

When passing secrets to a sandbox, use the name-only form to resolve values from the caller’s environment; however, v1.32.0 docs do not show a secrets option for `hf sandbox exec`. They document `--secrets` when creating a dedicated sandbox, then running commands with `hf sandbox exec`.

Examples:

```
hf sandbox create -s <SECRET_NAME>
```

```
hf sandbox exec <SANDBOX_ID> -- <COMMAND> [ARGS...]
```

```
hf jobs run -s MY_SECRET python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'
```

- why_it_matters: Pass a secret to a sandbox command without placing its value in the process argument list.
- before: The CLI accepted secret values as flag arguments, including `--secrets KEY=value`, which placed them in `argv`; shell history and Linux `/proc/<pid>/cmdline` could expose them.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.32.0>, <https://github.com/huggingface/huggingface_hub/pull/4835>, <https://github.com/huggingface/huggingface_hub/blob/v1.32.0/docs/source/en/guides/cli.md>, <https://github.com/huggingface/huggingface_hub/blob/v1.32.0/src/huggingface_hub/cli/sandbox.py>, <https://huggingface.co/docs/huggingface_hub/package_reference/cli>
- gotchas: "Version: v1.32.0"; "SANDBOX_ID (required): Sandbox id printed by `hf sandbox create`."; "COMMAND... (required): Command to run in the sandbox."; "-s, --secrets SECRET: Set a secret environment variable; prefer a name to read its value from the environment. Documented for sandbox creation and Jobs run, not sandbox exec."; "--secrets-file TEXT: Read secret environment variables from a file; `-` reads stdin. Documented for sandbox creation and Jobs run, not sandbox exec."; "--pool: For pooled sandboxes, secrets are unavailable; use `--env` instead."; "Prerequisite: The name-only secret form reads the value from the caller’s environment. An unset requested secret is an error."; "Prerequisite: An env or secrets file should be readable only by you (`chmod 600`); the CLI warns if it is not."; "Prerequisite: Pooled sandboxes have no encrypted secrets channel; the CLI directs users to pass values with `--env` or `--env-file`."; "The name-only form reads the value from the calling environment."; "A secrets file should be readable only by you (`chmod 600`); the CLI warns if it is not."; "The `-s MY_SECRET=psswrd` form remains supported, but the value appears in shell history and the process listing and the CLI warns."; "The source says pooled sandboxes do not support the secrets channel; use `--env` for pooled sandboxes."; "Docs conflict: The release note names `hf sandbox exec --secrets`, but the v1.32.0 CLI source defines `hf sandbox exec` with `--env`/`--env-file` and no `--secrets`/`--secrets-file`; those secret options are on sandbox creation. The documented name-only secret example is `hf jobs run`. The exact task command `hf sandbox exec --secrets` is therefore not documented; see not_found."

### hf jobs scheduled ls adds status, label, and name filters (2026-09-03)
- slug: hf-jobs-scheduled-ls-adds-status-label-and-name-filters-8f325f0b9f9d
- score: 0.97

How to use it:

When listing scheduled jobs, filter by status, labels, or name with `hf jobs scheduled ls`; migrate deprecated `-f`/`--filter` expressions to the corresponding flags because they are ignored and warn. In Python, pass label matches to `list_scheduled_jobs(labels=...)`.

Examples:

```
hf jobs scheduled ls --status suspended
```

```
hf jobs scheduled ls --name <NAME> --label env=prod
```

```
from huggingface_hub import list_scheduled_jobs
jobs = list_scheduled_jobs(labels={"env": "prod"})
```

- why_it_matters: List scheduled jobs by status, label, or name in a repository maintenance workflow.
- before: The release note's migration table replaces `-f name=daily-report` with `--name daily-report`, `-f env=prod` with `--label env=prod`, `-f suspend!=true` with the default or `--status active`, and `-f suspend=true` with `--status suspended`.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.30.0>, <https://huggingface.co/docs/huggingface_hub/v1.30.0/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/v1.30.0/en/guides/jobs>, <https://huggingface.co/docs/huggingface_hub/v1.30.0/en/package_reference/hf_api>
- gotchas: "Version: v1.30.0"; "--status: Filter by `active` or `suspended`; may be comma-separated or repeated. Cannot combine with `--all`."; "-a, --all: Show all scheduled jobs; default hides suspended jobs. Cannot combine with `--status`."; "-l, --label TEXT: Filter by a `key=value` label. Repeat to require multiple labels; all filters must match."; "--name TEXT: Filter by job name; shortcut for `--label name=NAME`."; "-f, --filter TEXT: Deprecated; use `--status` and `--label`. Release note says this option is accepted but ignored and warns; migrate existing filters."; "labels: `dict[str, str]` of label key/value pairs; returns scheduled jobs matching all supplied labels."; "`--status` accepts `active` or `suspended`."; "`-l`/`--label key=value` is repeatable."; "`--name` is a shortcut for `--label name=NAME`."; "`-f`/`--filter` is accepted but ignored and emits a warning; the option will be removed in a future release."

### hf buckets settings updates bucket visibility (2026-08-27)
- slug: hf-buckets-settings-updates-bucket-visibility-78cbd154b201
- score: 0.97

How to use it:

For an existing bucket, set `private=True` to make it private or `private=False` to make it public. Use `update_bucket_settings()` or `hf buckets settings` with the matching visibility option.

Examples:

```
hf buckets settings <owner>/<bucket> --private
```

```
hf buckets settings <owner>/<bucket> --public
```

```
from huggingface_hub import update_bucket_settings
update_bucket_settings(bucket_id="<owner>/<bucket>", private=True)
```

- why_it_matters: Change an existing bucket from private to public or public to private.
- before: Bucket visibility could only be set when creating a bucket; it could not be changed afterward.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.29.0>, <https://huggingface.co/docs/huggingface_hub/v1.29.0/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/v1.29.0/en/package_reference/hf_api>
- gotchas: "Version: v1.29.0"; "bucket_id (required): Bucket ID, such as `<owner>/<bucket>`."; "private (required): Boolean visibility setting: `True` makes the bucket private; `False` makes it public."; "--private (required): CLI option to make the bucket private."; "--public (required): CLI option to make the bucket public."; "BUCKET_ID (required): CLI bucket ID in `namespace/bucket_name` or `hf://buckets/namespace/bucket_name` format."; "Prerequisite: Use huggingface_hub v1.29.0 or later; the release introduced updating bucket visibility."

### hf endpoints deploy and update support managed engine images and parallelism settings (2026-08-18)
- slug: hf-endpoints-deploy-and-update-support-managed-engine-images-and-parallelism-set-1911ad7ea871
- score: 0.98

How to use it:

When deploying a vLLM or SGLang endpoint on a multi-accelerator instance, set parallelism to use the allocated accelerators. Use `hf endpoints deploy` to configure its engine image, or `hf endpoints update` to retune a running endpoint.

Examples:

```
hf endpoints deploy gpt-oss-120b-vllm --repo openai/gpt-oss-120b --framework custom --accelerator gpu --instance-size x8 --instance-type nvidia-h200 --region us-east-1 --vendor aws --engine vllm --custom-image vllm/vllm-openai:v0.23.0 --tensor-parallel-size 8
```

```
hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2
```

```
custom_image={"vLLM": {"url": "vllm/vllm-openai:v0.23.0", "healthRoute": "/health", "port": 8000, "tensorParallelSize": 1}}
```

- why_it_matters: Deploy or retune an Inference Endpoint using a custom engine image or multi-accelerator parallelism.
- before: Configure `custom_image` using the prior flat format and use other available endpoint settings; vLLM and SGLang defaulted to one accelerator despite an instance allocating every accelerator.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.28.0>, <https://huggingface.co/docs/huggingface_hub/en/guides/inference_endpoints>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.28.0"; "--engine: Managed engine image to run with `--custom-image`; documented values include vLLM and SGLang engines. Defaults to an arbitrary container."; "--custom-image: Docker image URL for the container; requires `--framework custom`. On update, replacing the image requires passing settings to keep."; "--tensor-parallel-size: Number of accelerators to shard one model copy across; for vLLM and SGLang."; "--data-parallel-size: Number of model copies to run, one per accelerator; for vLLM only."; "--health-route: Health check route exposed by the container; requires `--custom-image`."; "--port: Port the container listens on; requires `--custom-image`."; "custom_image.<engine>: Use an engine-name key such as `vLLM` or `sGLang`; its value is an object forwarded to the API when it has no top-level `url`."; "custom_image.<engine>.url: Container image URL."; "custom_image.<engine>.port: Container port."; "custom_image.<engine>.healthRoute: Container health check route."; "custom_image.<engine>.tensorParallelSize: Engine tuning option for tensor parallelism."; "Prerequisite: Deploy requires `--repo`, `--framework`, `--accelerator`, `--instance-size`, and `--instance-type`; valid hardware combinations also require `--vendor` and `--region`."; "Prerequisite: `--custom-image` requires `--framework custom`."; "A custom_image dictionary without a top-level `url` is forwarded to the API untouched."; "vLLM and SGLang default to a single accelerator while an endpoint is allocated every accelerator of its instance; the API rejects that misconfiguration."

### hf endpoints deploy and update support container engine flags (2026-08-07)
- slug: hf-endpoints-deploy-and-update-support-container-engine-flags-8bca6cf2165c
- score: 0.98

How to use it:

When deploying or tuning an Inference Endpoint with a managed engine image, set the command or arguments with the container flags; they do not require `--custom-image`. For an existing endpoint, pass the full replacement value, or an empty string to reset it; omit a flag to leave it unchanged.

Examples:

```
hf endpoints deploy <endpoint-name> --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl --region us-east-1 --vendor aws --container-args "--max-model-len 8192"
```

```
hf endpoints update <endpoint-name> --container-args "--enable-auto-tool-choice --tool-call-parser lfm2"
```

```
hf endpoints update <endpoint-name> --container-args ""
```

- why_it_matters: When deploying or tuning an Inference Endpoint that uses a managed engine image, set or change its engine command or arguments.
- before: The v1.26.0 guide showed CLI deployment with `--container-command` and `--container-args` alongside `--custom-image`; the release note says updating these values was previously available through the UI or raw API.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.27.0>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/main/package_reference/inference_endpoints>, <https://huggingface.co/docs/huggingface_hub/v1.26.0/en/guides/inference_endpoints>
- gotchas: "Version: v1.27.0"; "NAME / endpoint name (required): Name of the Inference Endpoint."; "--repo (required): Model repository for the endpoint."; "--framework (required): Machine learning framework used for the model."; "--accelerator (required): Hardware accelerator for inference."; "--instance-size (required): Instance size for hosting the model."; "--instance-type (required): Cloud instance type for deployment."; "--region (required): Cloud region for deployment."; "--vendor (required): Cloud provider for deployment."; "--container-command: Overrides the container entrypoint; pass a quoted string split into tokens. On update, replaces the current value; empty string clears it."; "--container-args: Sets arguments for the container entrypoint; pass a quoted string split into tokens. On update, replaces current arguments rather than adding to them; empty string clears them."; "container_command: Optional `list[str]` overriding the entrypoint; maps to `model.command` and works with managed engine and custom images."; "container_args: Optional `list[str]` of arguments for the entrypoint; maps to `model.args` and works with managed engine and custom images."; "Prerequisite: For deploy, the docs require valid `--vendor`, `--region`, `--accelerator`, `--instance-type`, and `--instance-size` combinations; `hf endpoints hardware` lists them."; "Prerequisite: The API update methods allow all arguments to be omitted, but require at least one update argument."; "`--health-route` and `--port` still require `--custom-image`."; "Values replace rather than append; an empty string resets to the image default, and omitting the flag leaves the value unchanged."

### hf jobs ls adds name filtering and a NAME column (2026-07-30)
- slug: hf-jobs-ls-adds-name-filtering-and-a-name-column-26dd30565d8b
- score: 0.97

How to use it:

When listing Jobs by name, run `hf jobs ls -a --name <name>`; read the dedicated `NAME` column in the results. The name filter is a shortcut for `--label name=<name>`.

Examples:

```
hf jobs ls -a --name training-v2
```

- why_it_matters: When listing Jobs by name, use the CLI name filter and read the dedicated name column.
- before: Use `--label name=NAME` to filter Jobs; the name was shown only inside `labels`.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.26.0>, <https://github.com/huggingface/huggingface_hub/pull/4568>, <https://huggingface.co/docs/huggingface_hub/v1.26.0/guides/cli>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.26.0"; "--name TEXT: Only show Jobs with the given name; shortcut for `--label name=NAME`."; "-a, --all: Show all Jobs; default listing shows running and scheduling Jobs. Cannot be combined with `--status`."; "--label TEXT: Filter by a `key=value` label; repeat to require several labels."; "The name remains in `labels` for compatibility."

### hf Jobs CLI and Python API accept optional names (2026-07-17)
- slug: hf-jobs-cli-and-python-api-accept-optional-names-251232a70e68
- score: 0.93

How to use it:

When creating or organizing a Hub Job, add a name to make it easier to find in the UI. Use `--name` when creating or `hf jobs labels` to name an existing Job; names are optional and need not be unique.

Examples:

```
hf jobs run --name training-v2 python:3.12 python train.py
```

```
hf jobs labels <job_id> --name training-v2
```

```
hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'
```

- why_it_matters: When creating or organizing Hub Jobs, assign a name that makes the Job easier to find and identify in the UI.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.24.0>, <https://github.com/huggingface/huggingface_hub/pull/4532>, <https://huggingface.co/docs/huggingface_hub/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/main/en/guides/jobs>
- gotchas: "Version: v1.24.0"; "--name TEXT / name: Name the Job; stored as the `name` label. Names need not be unique."; "JOB_ID (`<job_id>`) (required): ID of the existing Job to update."; "SCHEDULE (required): Scheduled run interval; supports `@hourly` and documented cron expressions."; "IMAGE (required): Docker image used by the scheduled Job."; "COMMAND... (required): Command to run in the scheduled Job."; "Prerequisite: You can manage Jobs you own or Jobs in organizations where you have write permission; Jobs are pay-as-you-go."; "Names are optional and do not need to be unique."

### hf extensions update updates installed CLI extensions (2026-07-09)
- slug: hf-extensions-update-updates-installed-cli-extensions-7cf778957179
- score: 0.90

How to use it:

When an installed extension needs updating, run `hf extensions update <name>`; to check all installed extensions, run `hf extensions update`. Up-to-date extensions are skipped, and the command errors if the named extension is not installed.

Examples:

```
hf extensions update <name>
```

```
hf extensions update
```

- why_it_matters: Update an installed CLI extension while maintaining the repository development workflow.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.23.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.23.0/docs/source/en/guides/cli-extensions.md>
- gotchas: "Version: v1.23.0"; "[NAME]: Extension to update; accepts a name with or without the `hf-` prefix, optionally as `OWNER/hf-<name>`. If omitted, checks all installed extensions and updates outdated ones."; "Prerequisite: The target extension must already be installed; otherwise the command raises an error."; "A single-extension update accepts `<name>`, `hf-<name>` or `OWNER/hf-<name>`."; "Python extensions reuse their existing venv; binary extensions are overwritten."

### hf models ls adds inference provider, pipeline, gated, and app filters (2026-07-09)
- slug: hf-models-ls-adds-inference-provider-pipeline-gated-and-app-filters-c6f140f49ab4
- score: 0.96

How to use it:

When narrowing a Hub model listing by provider, pipeline tag, gated status, or app support, run `hf models ls` with the matching filters.

Examples:

```
hf models ls --inference-provider <provider>
```

```
hf models ls --pipeline-tag <task> --gated
```

```
hf models ls --apps <app>
```

- why_it_matters: Narrow a repository model listing by inference provider, pipeline tag, gated status, or app support.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.23.0>, <https://huggingface.co/docs/huggingface_hub/package_reference/cli>
- gotchas: "Version: v1.23.0"; "--inference-provider <provider>: Filters models served by the specified inference provider; the docs list allowed provider values."; "--pipeline-tag <task>: Filters by pipeline tag (canonical task), such as `summarization`."; "--gated / --no-gated: Selects gated models only (`--gated`) or non-gated models only (`--no-gated`). These are alternatives."; "--apps <app>: Filters by app or apps that can run the model; may be repeated."; "Prerequisite: The release note identifies these filters as added in v1.23.0; use that version or later."

### hf spaces templates can create Spaces from templates (2026-07-09)
- slug: hf-spaces-templates-can-create-spaces-from-templates-3a99aa03efeb
- score: 0.98

How to use it:

When creating a Space from an official Hub template, list templates with `hf spaces templates`, then create the Space with `hf repos create <repo_id> --type space --template <template>`. A template recommended as private defaults to private unless you choose a visibility.

Examples:

```
hf spaces templates
```

```
hf repos create <repo_id> --type space --template <template>
```

- why_it_matters: Create a new Space in the repository from an official Hub template.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.23.0>, <https://huggingface.co/docs/huggingface_hub/v1.29.0/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/main/en/guides/repository>
- gotchas: "Version: v1.23.0"; "REPO_ID (required): New repository ID; for example, `<owner>/<name>`."; "--type space (required): Sets the repository type to Space."; "--template TEXT (required): Official template repo ID or short name; Spaces only."; "--private / --no-private: Choose private or non-private creation. The docs do not state these options are mutually exclusive."; "--public: Choose public creation; ignored if the repository already exists."; "--token TEXT: User Access Token for authentication."; "Prerequisite: You can manage repositories you own or repositories in organizations where you have write permission."; "Templates come from the official Hub template set."; "Templates recommended as private, such as JupyterLab, are created privately by default unless visibility is explicitly chosen."; "Docs conflict: Newer docs say `space_sdk` is still required for the SDK API, while the v1.23.0 release note says the SDK is inferred from the template. This concerns the SDK API; it does not establish a CLI conflict."

### hf adds discussions edit command (2026-07-03)
- slug: hf-adds-discussions-edit-command-18be0c94ba8d
- score: 0.96

How to use it:

When a discussion comment needs updating, retrieve its comment ID with `hf discussions info`, then edit it with `hf discussions edit`.

Examples:

```
hf discussions info <owner>/<repo> <discussion_number>
```

```
hf discussions edit <owner>/<repo> <discussion_number> <comment_id> --body "<updated comment>"
```

- why_it_matters: Edit a discussion from the CLI while maintaining a repository.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.22.0>, <https://huggingface.co/docs/huggingface_hub/main/guides/cli>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.22.0"; "REPO_ID (required): Repository ID, such as `<owner>/<repo>`."; "NUM (required): Discussion or pull request number."; "COMMENT_ID (required): ID of the comment to edit; retrieve it with `hf discussions info`."; "--body TEXT: New comment text; supports Markdown."; "--body-file PATH: Read the new comment from a file; `-` reads stdin."; "--type / --repo-type: Repository type: model, dataset, space, or kernel; defaults to model."; "--token: Hugging Face user access token."

### hf adds Python and CLI sandbox workflows on Jobs (2026-07-03)
- slug: hf-adds-python-and-cli-sandbox-workflows-on-jobs-02c551521221
- score: 0.99

How to use it:

When you need to run repository code in an isolated cloud machine and retrieve its output or files, create a sandbox, run the command, and use the file API or CLI copy command to move files. Use a dedicated `Sandbox.create` VM or a `SandboxPool` for shared CPU sandboxes.

Examples:

```
from huggingface_hub import Sandbox

with Sandbox.create(image="<image>") as sbx:
    result = sbx.run("<command>")
    print(result.stdout)
    sbx.files.write("<sandbox_path>", "<file_contents>")
```

```
from huggingface_hub import SandboxPool

with SandboxPool(image="<image>", flavor="cpu-basic", warm_up=2) as pool:
    sbx = pool.create()
    print(sbx.run("<command>").stdout)
```

```
hf sandbox create
hf sandbox exec <sandbox_id> -- <command> [<arg> ...]
hf sandbox cp <local_path> <sandbox_id>:<sandbox_path>
hf sandbox cp <sandbox_id>:<sandbox_path> <local_path>
hf sandbox kill <sandbox_id>
```

- why_it_matters: Run repository code in an isolated cloud machine and retrieve its output or files.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.22.0>, <https://huggingface.co/docs/huggingface_hub/guides/sandbox>, <https://huggingface.co/docs/huggingface_hub/package_reference/sandbox>, <https://github.com/huggingface/hf-sandbox>
- gotchas: "Version: v1.22.0"; "Sandbox.create(image): Docker image for the dedicated sandbox; defaults to `python:3.12`."; "Sandbox.run(command) (required): Shell string or argv list to execute; waits for completion and returns command output."; "SandboxPool(image): Image used by the pool; defaults to `python:3.12`."; "SandboxPool(flavor): Host hardware flavor; defaults to `cpu-basic`."; "SandboxPool(warm_up): Number of host jobs to pre-provision; defaults to 1."; "hf sandbox exec <sandbox_id> -- <command> [args] (required): Sandbox id and command plus its arguments. CLI docs say output is streamed and exit code propagated."; "hf sandbox cp <local_path> <sandbox_id>:<sandbox_path> (required): Local source and sandbox destination for copying a file into the sandbox."; "hf sandbox cp <sandbox_id>:<sandbox_path> <local_path> (required): Sandbox source and local destination for copying a file out."; "hf sandbox kill <sandbox_id> (required): Sandbox id to terminate."; "Prerequisite: Install `huggingface_hub` version 1.22.0 or later to use the Sandbox API and `hf sandbox` CLI."; "Prerequisite: The sandbox image must provide `/bin/sh`."; "Prerequisite: Hub authentication is needed to create and manage sandboxes; the docs describe using the same HF token for later reconnection."; "Sandboxes are built on Jobs; any Docker image with `/bin/sh` works and sandboxes inherit Jobs' billing, hardware flavors, and namespace permissions."; "`Sandbox.create` provides a dedicated VM for GPU workloads, untrusted code, and full isolation; `SandboxPool` packs many cheap CPU sandboxes into a few shared host VMs for fan-out workloads."

### hf jobs run accepts local directories for volume mounts (2026-07-03)
- slug: hf-jobs-run-accepts-local-directories-for-volume-mounts-88e8a1dbb10d
- score: 0.95

How to use it:

When a Job needs files from a local repository directory, pass that directory to `-v`; Hugging Face syncs it to the `jobs-artifacts` bucket and mounts it. For Python Jobs, use `sync_job_volume` to create a mountable volume.

Examples:

```
hf jobs run -v ./<local-dir>:/<mount-path> <image> <command> [<args>...]
```

```
hf jobs uv run -v ./<local-dir>:/<mount-path> <script.py> [<args>...]
```

```
from huggingface_hub import run_uv_job, sync_job_volume
volume = sync_job_volume("./<local-dir>", "/<mount-path>")
run_uv_job("<script.py>", volumes=[volume])
```

- why_it_matters: Run a Job that needs files from a local repository directory mounted as a volume.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.22.0>, <https://huggingface.co/docs/huggingface_hub/main/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/main/en/guides/jobs>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md>, <https://huggingface.co/docs/huggingface_hub/main/en/package_reference/hf_api>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/cli.md>
- gotchas: "Version: v1.22.0"; "-v, --volume: Repeatable volume mount argument: `LOCAL_DIR:/MOUNT_PATH[:ro|:rw]`. The mount path is required and absolute. Local directory volumes default to read-only; `:rw` enables writes."; "sync_job_volume(source) (required): Local directory path to sync."; "sync_job_volume(mount_path) (required): Absolute mount path inside the Job container; must start with `/`."; "sync_job_volume(remote_name): Bucket subfolder name; defaults to a name derived from the source path and machine hostname."; "sync_job_volume(read_only): Defaults to `True`; set `False` to allow the Job to write to the bucket folder."; "sync_job_volume(namespace): Namespace owning the `jobs-artifacts` bucket; defaults to the current user's namespace. Use the same namespace as the Job."; "sync_job_volume(token): Access token; defaults to the locally saved token. `False` disables authentication."; "Prerequisite: Hugging Face Jobs require pre-paid credits for the user or organization."; "Prerequisite: Authenticate with Hugging Face; `sync_job_volume` uses the locally saved token by default."; "The local directory is synced to a `jobs-artifacts` bucket and mounted."

### hf jobs scheduled trigger runs a scheduled Job on demand (2026-07-03)
- slug: hf-jobs-scheduled-trigger-runs-a-scheduled-job-on-demand-1ffa2f2a2b3e
- score: 0.97

How to use it:

When a scheduled Job needs to run before its next scheduled time, run `hf jobs scheduled trigger` with its ID. This triggers it immediately without changing its schedule.

Examples:

```
hf jobs scheduled trigger <scheduled_job_id>
```

- why_it_matters: Trigger a scheduled Job on demand while maintaining a repository's scheduled development workflow.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.22.0>, <https://huggingface.co/docs/huggingface_hub/en/guides/cli>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.22.0"; "SCHEDULED_JOB_ID (required): Scheduled Job ID; use `namespace/scheduled_job_id` when specifying a namespace in the ID."; "--namespace TEXT: Namespace where the Job runs; defaults to the current user's namespace."; "--token TEXT: User Access Token."

### hf jobs ls and list_jobs support server-side filters and lazy pagination (2026-06-25)
- slug: hf-jobs-ls-and-list-jobs-support-server-side-filters-and-lazy-pagination-a34644f7fa95
- score: 0.97

How to use it:

When listing Jobs, use `list_jobs(status=..., labels=...)` to filter server-side and iterate its paginated results lazily; use `hf jobs ls` with `--status`, repeated `--label`, and `--limit` to filter and cap CLI output. Use `--limit 0` to show all Jobs.

Examples:

```
from huggingface_hub import list_jobs

for job in list_jobs(status=["RUNNING", "SCHEDULING"], labels={"env": "prod"}):
    print(job.id)
```

```
hf jobs ls --status running,scheduling --label env=prod --label team=ml --limit 500
```

```
hf jobs ls -a --limit 0
```

- why_it_matters: List and process Jobs in a repository, filtering by status or labels and handling large result sets.
- before: The CLI used `-f`/`--filter` for client-side filtering, including glob patterns, negation, and filtering by `id`, `image`, or `command`; `list_jobs()` returned results without lazy page-by-page iteration.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.21.0>, <https://github.com/huggingface/huggingface_hub/pull/4395>, <https://huggingface.co/docs/huggingface_hub/guides/jobs>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.21.0"; "list_jobs(status): A status string or list of statuses; examples include `RUNNING` and `SCHEDULING`."; "list_jobs(labels): A dictionary of label key/value pairs used to filter Jobs."; "--status: Filters by status; accepts comma-separated or repeated statuses. Cannot be combined with `-a`/`--all`."; "-l, --label TEXT: Filters by `key=value` label; repeat to require several labels. A Job must match every filter."; "-a, --all: Shows all Jobs; cannot be combined with `--status`."; "--limit INTEGER: Maximum Jobs displayed; default is 100. Set to 0 for no limit."; "-f, --filter TEXT: Deprecated; use `--status` and `--label` instead."; "`-f`/`--filter` is deprecated."; "Glob patterns (`data-*`), negation (`key!=value`), and filtering by `id`, `image`, or `command` are no longer supported."

### hf auth login uses browser OAuth and JSON events (2026-06-18)
- slug: hf-auth-login-uses-browser-oauth-and-json-events-05c9b853e48c
- score: 0.94

How to use it:

When authenticating from an agent, run the JSON login flow and relay the device URL and code; wait for the terminal success or error event. Use `get_token()` to retrieve and transparently refresh a stored OAuth token, and `hf auth list` to inspect stored tokens.

Examples:

```
hf auth login --format json
```

```
from huggingface_hub import login
login()
```

```
from huggingface_hub import get_token
token = get_token()
```

- why_it_matters: Authenticate the CLI or Python client from an interactive terminal or coding agent and keep an OAuth token usable for long-running work.
- before: For CLI login, copy-paste a token; in Python, use the prior `login()` behavior.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.20.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.20.0/src/huggingface_hub/cli/auth.py>, <https://github.com/huggingface/huggingface_hub/blob/v1.20.0/src/huggingface_hub/_login.py>, <https://github.com/huggingface/huggingface_hub/blob/v1.20.0/src/huggingface_hub/utils/_auth.py>, <https://huggingface.co/docs/huggingface_hub/package_reference/authentication>
- gotchas: "Version: v1.20.0"; "--format json: Select JSON output for agent login events; `device_code` contains the verification URL and user code, followed by an authentication terminal event."; "login(token=None): Omitting `token` uses browser OAuth; in a terminal, the user can choose browser login or paste a token."; "login(add_to_git_credential=False): Save the supplied token as a Git credential; ignored for browser login."; "login(skip_if_logged_in=True): Skip prompting if already logged in; set false to force re-login."; "Prerequisite: Install `huggingface_hub` to use its `hf` CLI and Python login API."; "Prerequisite: Browser login requires completing authorization at the displayed URL with the displayed code."; "OAuth tokens expire after 30 days."; "Token refresh occurs when less than a day of validity remains."; "The interactive terminal offers the arrow-key choice menu; agent execution does not prompt and instead streams structured events."; "Docs conflict: The later v1.20.1 CLI guide says `hf auth login` does not support `--format json` or `--format quiet` and shows `--format agent` instead. This differs from the v1.20.0 release note; do not apply the later syntax to v1.20.0. https://huggingface.co/docs/huggingface_hub/v1.20.1/en/guides/cli"

### hf endpoints deploy accepts custom container settings (2026-06-18)
- slug: hf-endpoints-deploy-accepts-custom-container-settings-45a9f0fdb8a1
- score: 0.98

How to use it:

When deploying a repository model in a custom Docker image, run `hf endpoints deploy` with `--framework custom` and `--custom-image`, then add the documented container, environment, and access settings you need.

Examples:

```
hf endpoints deploy <endpoint-name> --repo <owner/repo> --framework custom --accelerator <cpu|gpu|neuron> --vendor <vendor> --region <region> --instance-type <instance-type> --instance-size <size> --custom-image <image-url> --health-route <route> --port <port> --container-args "<launch arguments>" --env <KEY=value> --type authenticated
```

- why_it_matters: Deploy a custom container for a repository model from a coding workflow.
- before: Hand-write JSON and POST the raw endpoints API to deploy a custom container.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.20.0>, <https://github.com/huggingface/huggingface_hub/pull/4329>, <https://github.com/huggingface/huggingface_hub/blob/v1.20.0/docs/source/en/guides/cli.md>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/guides/inference_endpoints>
- gotchas: "Version: v1.20.0"; "NAME (required): Endpoint name."; "--repo (required): Model repository associated with the endpoint."; "--framework (required): Model framework; use `custom` for a custom container."; "--accelerator, --vendor, --region, --instance-type, --instance-size (required): Specify endpoint hardware and cloud placement; run `hf endpoints hardware` for valid combinations."; "--custom-image: Docker image URL; required when using `--health-route` or `--port`. The custom-container guide uses it with `--framework custom`."; "--health-route: Health check route exposed by the container; requires `--custom-image`."; "--port: Port the container listens on; requires `--custom-image`."; "--container-args: Quoted launch string passed as container arguments."; "--container-command: Quoted launch string overriding the container entrypoint. The v1.20.0 guide names this option; it does not document `--command`."; "--env: Inject environment variables; the documented form is `KEY=value`."; "--secrets: Inject secrets into the container environment."; "--type: Endpoint access type: `public`, `authenticated`, or `private`; defaults to `authenticated`."; "container_command: SDK `create_inference_endpoint` parameter: list of tokens overriding the container entrypoint command."; "container_args: SDK `create_inference_endpoint` parameter: list of tokens appended to the container entrypoint."; "Prerequisite: Install the `hf` CLI and authenticate to Hugging Face to use the Hub."; "Prerequisite: The model repository is mounted at `/repository` inside the container."; "The model repository is mounted at `/repository` inside the container."; "The custom-container flags require `--custom-image`."; "Passing `protected` for `--type` emits a `FutureWarning`."; "Docs conflict: The supplied release note names `--command`; the v1.20.0 official CLI guide documents `--container-command` instead."

### hf jobs wait blocks for terminal job outcomes (2026-06-18)
- slug: hf-jobs-wait-blocks-for-terminal-job-outcomes-24dc7b412eee
- score: 0.97

How to use it:

When chaining steps after Hugging Face Jobs finish, use `hf jobs wait` for one or more IDs; it returns success only when every Job completed. Set `--timeout` to cap the wait, and use `&&` to run the next step only on success.

Examples:

```
hf jobs wait <job_id> && next-step
```

```
hf jobs wait <id1> <id2> --timeout 10m
```

```
hf jobs wait <job_id> [<job_id>...]
```

- why_it_matters: Chain CI or shell steps after one or more Hugging Face Jobs finish, and act on their result.
- before: Use `hf jobs ssh` while the Job is still scheduling only after it becomes available; it previously failed immediately before the Job was running. Non-detached `hf jobs run` and `hf jobs uv run` previously exited 0 regardless of Job outcome.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.20.0>, <https://github.com/huggingface/huggingface_hub/pull/4345>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.20.0"; "JOB_IDS... (required): One or more Job IDs, or `namespace/job_id`; every Job must belong to the same namespace."; "--timeout TEXT: Maximum wait duration; accepts an integer followed by `s` (seconds, default unit), `m` (minutes), `h` (hours), or `d` (days)."; "--namespace TEXT: Namespace where the Job runs; defaults to the current user’s namespace."; "--token TEXT: Hugging Face User Access Token."; "`hf jobs wait` exits 0 only if all waited-on Jobs ended `COMPLETED`."; "`wait_for_job` returns final `JobInfo` on failure and only raises `TimeoutError` on timeout."; "SSH launch requires `--ssh` and an SSH key registered on huggingface.co/settings/keys."

### hf spaces wait waits for a Space runtime state (2026-06-18)
- slug: hf-spaces-wait-waits-for-a-space-runtime-state-07f6adc5a81d
- score: 0.98

How to use it:

After restarting a Space, wait until it leaves an intermediate runtime stage. Run `hf spaces wait <owner>/<space>` and continue only if it reaches `RUNNING` (exit code 0).

Examples:

```
hf spaces restart <owner>/<space> && hf spaces wait <owner>/<space>
```

```
hf spaces wait <owner>/<space> --timeout 5m
```

```
from huggingface_hub import restart_space, wait_for_space
restart_space("<owner>/<space>")
runtime = wait_for_space("<owner>/<space>")
runtime.stage
```

- why_it_matters: Restart a Space and wait for it to reach a final runtime state before continuing a repository workflow.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.20.0>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md>, <https://huggingface.co/docs/huggingface_hub/main/package_reference/hf_api>
- gotchas: "Version: v1.20.0"; "SPACE_ID (required): Space ID, such as `<owner>/<space>`."; "--timeout: Maximum time to wait; accepts a duration with `s`, `m`, `h`, or `d` units. Defaults to seconds."; "repo_id (required): ID of the Space to wait for."; "timeout: Maximum wait time in seconds; `None` waits indefinitely."; "poll_interval: Seconds between status checks; defaults to 1 second."; "token: User access token; defaults to the locally saved token. Set to `False` to disable authentication."; "The CLI exits 0 when the Space is `RUNNING` and non-zero otherwise."

### hf buckets CLI accepts browser URLs (2026-06-11)
- slug: hf-buckets-cli-accepts-browser-urls-b942b86d7bad
- score: 0.96

How to use it:

When listing files from a bucket browser URL, pass the URL as the argument to `hf buckets ls`.

Examples:

```
hf buckets ls https://huggingface.co/buckets/commoncrawl/commoncrawl
```

- why_it_matters: List a bucket from its browser URL while working with repository data.
- before: The release note says the command previously rejected browser URLs with an invalid bucket path error; use a supported bucket path form such as namespace/name or hf://buckets/namespace/name.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.19.0>, <https://github.com/huggingface/huggingface_hub/pull/4315>, <https://huggingface.co/docs/huggingface_hub/v1.19.0/en/package_reference/cli>
- gotchas: "Version: v1.19.0"; "ARGUMENT (required): Namespace to list buckets, or bucket ID to list files; v1.19.0 release notes document a Hugging Face bucket browser URL as accepted input."; "-h, --human-readable: Show sizes in human-readable format."; "--tree: List files in tree format; only for file listings."; "-R, --recursive: List files recursively; only for file listings."; "--search TEXT: Search query."; "--token TEXT: User access token."; "Non-URL path behavior is unchanged."

### hf jobs exposes container ports through the jobs proxy (2026-06-11)
- slug: hf-jobs-exposes-container-ports-through-the-jobs-proxy-25c667fa5951
- score: 0.98

How to use it:

When a repository development server runs in an HF Job, pass its port with `--expose` or `expose` when creating the job. Use the returned `expose_urls` to reach it; accessing the URL requires an HF token with read access to the job's namespace.

Examples:

```
hf jobs run --expose 8000 python:3.12 python -m http.server 8000
```

```
from huggingface_hub import run_job
job = run_job(image="python:3.12", command=["python", "-m", "http.server", "8000"], expose=[8000])
job.status.expose_urls
```

- why_it_matters: Run a repository development server in a Hugging Face Job and make its port reachable for review.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.19.0>, <https://huggingface.co/docs/huggingface_hub/v1.19.0/en/guides/jobs>, <https://huggingface.co/docs/huggingface_hub/v1.19.0/en/package_reference/jobs>
- gotchas: "Version: v1.19.0"; "--expose INTEGER: Container port to expose through the jobs proxy; repeat the flag to expose multiple ports. URL access requires an HF token with read access to the job's namespace."; "image (required): Docker image for the job; example uses `python:3.12`."; "command (required): Command to run in the job; example starts Python's HTTP server on port 8000."; "expose: List of container ports to expose through the proxy, e.g. `[8000]`."; "JobStatus.expose_urls: List of public URLs for exposed ports; `None` when no port is exposed. Each URL uses `https://<job_id>--<port>.hf.jobs`. Access requires an HF token with read access to the job's namespace."; "Prerequisite: The machine must be logged in to run and manage Jobs."; "Prerequisite: Jobs are available to Pro users and Team or Enterprise organizations."; "Prerequisite: Accessing an exposed URL requires an HF token with read access to the Job's namespace."; "Exposed ports require an HF token with read access to the job's namespace."; "Works on `hf jobs run`, `hf jobs uv run`, and their scheduled variants."

### hf upload and hf download accept hf:// URIs (2026-06-11)
- slug: hf-upload-and-hf-download-accept-hf-uris-2f7865e5a6b8
- score: 0.98

How to use it:

When uploading or downloading a repository file by URI, pass `hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]` as the repository destination/source. Keep the URI as the source of repo type, revision, and path; omit `--repo-type` and `--revision`, and omit `path_in_repo` for upload or positional filenames for download when the URI contains a path.

Examples:

```
hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet
```

```
hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv
```

- why_it_matters: Upload or download a repository file using a single URI that specifies its repository type, revision, and path.
- before: Pass repository ID, repo type and revision separately; supply the file path as a download positional filename or upload `path_in_repo`.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.19.0>, <https://huggingface.co/docs/huggingface_hub/v1.19.0/en/guides/cli>
- gotchas: "Version: v1.19.0"; "URI `<TYPE>`: Optional repository type, such as `datasets`; when omitted, the URI defaults to a model repository."; "URI `<ID>` (required): Repository ID."; "URI `<REVISION>`: Revision such as a branch, tag, or commit; URI encodes it, so do not also set `--revision`."; "URI `<PATH>`: File or subfolder path in the repository; when present, do not also pass positional filenames to download or `path_in_repo` to upload."; "`local_path` (required): Upload source file or folder on the local machine."; "`--repo-type`: Normally selects repository type; cannot be set when using an `hf://` URI."; "`--revision`: Normally selects revision; cannot be set when using an `hf://` URI."; "Prerequisite: Install the `hf` CLI; the v1.19.0 guide documents the standalone installer, pip, and Homebrew options."; "Prerequisite: Uploading requires a token; the CLI uses the locally saved token from `hf auth login` by default."; "Prerequisite: Accessing private or gated repositories for download requires a token; a locally saved token is used by default."; "A URI with a path cannot be combined with positional filenames for download or `path_in_repo` for upload."

### hf CLI accepts Hugging Face web URLs (2026-06-05)
- slug: hf-cli-accepts-hugging-face-web-urls-b92533719b10
- score: 0.97

How to use it:

When a Hub file is identified by a Hugging Face web URL, pass that URL to `parse_hf_uri` or use it as `SRC` in `hf cp` to read the file.

Examples:

```
from huggingface_hub import parse_hf_uri
uri = parse_hf_uri("https://huggingface.co/datasets/<namespace>/<name>/blob/<revision>/<path>")
```

```
hf cp https://huggingface.co/nvidia/LocateAnything-3B/blob/main/config.json - | jq '.architectures'
```

- why_it_matters: When reading a Hub file during repository work, pass its Hugging Face web URL directly to the CLI or library parser.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.18.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.18.0/docs/source/en/package_reference/hf_uris.md>, <https://github.com/huggingface/huggingface_hub/blob/v1.18.0/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.18.0"; "parse_hf_uri(uri) — `uri` (required): HF URI or Hugging Face URL to parse; returns an `HfUri`."; "parse_hf_uri(uri, endpoint=...) — `endpoint`: Custom Hub base URL; recognizes web URLs on that endpoint."; "hf cp — `SRC` (required): Source file; docs list local files, `hf://` URIs, or `-` for stdin. Release-note example uses a Hugging Face web URL."; "hf cp — `[DST]`: Destination path or `-` for stdout."; "hf cp — `--token TEXT`: User Access Token."

### hf cp copies files among local paths, Hub repos, and buckets (2026-06-05)
- slug: hf-cp-copies-files-among-local-paths-hub-repos-and-buckets-bd2e3c614c5c
- score: 0.98

How to use it:

When copying a file between a local path and Hub storage, or between supported Hub locations, use `hf cp` with the source and destination paths. Use `-` for stdin or stdout; for Hub folder copies, a trailing `/` on the source copies its contents.

Examples:

```
hf cp ./model.safetensors hf://username/my-model/model.safetensors
```

```
hf cp hf://username/my-model/config.json - | jq .
```

```
hf cp hf://username/source-model/config.json hf://username/dest-model/config.json
```

- why_it_matters: When copying files between a local workspace and Hub storage, or between remote locations, use the unified copy command with the applicable source and destination.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.18.0>, <https://huggingface.co/docs/huggingface_hub/v1.20.1/en/guides/cli>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.18.0"; "SRC (required): Source: local file, `hf://` URI for a repo or bucket, or `-` for stdin."; "DST: Destination: local path, `hf://` URI for a repo or bucket, or `-` for stdout."; "--token TEXT: User Access Token; docs identify token generation at Hugging Face settings."; "trailing `/` on Hub source path: For Hub folder copies, copies the folder contents rather than nesting the folder itself."; "`-` as SRC or DST: Use `-` as source for stdin or destination for stdout."; "Remote-to-remote copies only work within the same storage region."; "Bucket-to-repo copies are not yet supported."; "Docs conflict: Current docs specify `hf cp` copies a single file when a local path is involved; whole local directories require `hf upload`/`hf download` for repos or `hf buckets sync` for buckets. The release note describes trailing-slash folder-content semantics without this local-path limitation."

### hf copy_files and hf buckets cp copy between repositories (2026-05-28)
- slug: hf-copy-files-and-hf-buckets-cp-copy-between-repositories-861d3ffa5b77
- score: 0.97

How to use it:

When copying files or folders between Hub repositories, use `copy_files` with `hf://` source and destination URIs; use `hf buckets cp` for CLI repo-to-repo file copies. For direct `CommitOperationCopy` cross-repository sources, set `src_repo_id` and `src_repo_type` (required when `src_repo_id` is set).

Examples:

```
from huggingface_hub import copy_files

copy_files(
    "hf://datasets/<owner>/<source-repo>/data/",
    "hf://datasets/<owner>/<target-repo>/data/",
)
```

```
hf buckets cp hf://<owner>/<source-repo>/config.json hf://<owner>/<target-repo>/config.json
```

```
CommitOperationCopy(src_path_in_repo="<source-path>", path_in_repo="<destination-path>", src_repo_id="<owner>/<source-repo>", src_repo_type="<model|dataset|space>")
```

- why_it_matters: Copy files or a folder between Hub repositories without downloading and re-uploading the data.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.17.0>, <https://huggingface.co/docs/huggingface_hub/v1.20.1/en/guides/upload>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/cli.md?plain=1>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/upload.md>
- gotchas: "Version: v1.17.0"; "source URI / `src_path_in_repo` (required): Source file or folder URI for `copy_files`; source repository path for `CommitOperationCopy`."; "destination URI / `path_in_repo` (required): Destination URI for `copy_files`; destination repository path for `CommitOperationCopy`."; "`src_repo_id`: Source repository ID; defaults to the destination repository. If set, `src_repo_type` is required."; "`src_repo_type`: Source repository type: `model`, `dataset`, or `space`; required when `src_repo_id` is set."; "`src_revision`: Revision to copy the source file from."; "CLI `SRC` and `DST` (required): The source and destination locations; each can be a local path, `hf://` URI, or `-` for stdin/stdout."; "Prerequisite: For Hub uploads, the docs say to log in to a Hugging Face account."; "Supports model-to-model, model-to-dataset, and other repository combinations."; "LFS blobs are deduplicated server-side; non-LFS files are fetched from the source repository and committed as regular payloads."

### hf jobs accepts unknown server-side hardware flavors (2026-05-28)
- slug: hf-jobs-accepts-unknown-server-side-hardware-flavors-6b1ae8685989
- score: 0.93

How to use it:

When a Hub Job needs a server-side hardware flavor the CLI does not know, pass it with `--flavor` to `hf jobs run`.

Examples:

```
hf jobs run --flavor future-gpu-x99 python:3.12 echo "works with unknown flavors"
```

- why_it_matters: Run a Hub Job using a flavor that the current CLI does not know so it can request a newer server-side flavor.
- before: CLI validation rejected flavor values it did not know.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.17.0>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/en/guides/jobs>
- gotchas: "Version: v1.17.0"; "--flavor <flavor>: Selects the Job hardware flavor; defaults to `cpu-basic` in CLI reference docs. The v1.17.0 release note says this flag accepts any string, including unknown flavors."; "IMAGE (required): Docker image to use; here `python:3.12`."; "COMMAND... (required): Command to run in the image; here `echo \"works with unknown flavors\"`."; "Prerequisite: The machine must be logged in. Jobs require a positive credit balance."; "`JobHardware` is now its own enum, independent of `SpaceHardware`."; "The former `JobHardware` dataclass return type of `list_jobs_hardware()` is renamed `JobHardwareInfo`."; "A daily CI workflow syncs both enums from the live Hub API and opens a bot PR when something changes."; "Docs conflict: The CLI reference page lists `--flavor` as a fixed set of choices, while the v1.17.0 release note says the flag accepts any string. The release note describes the v1.17.0 behavior; the CLI reference page does not document that change."

### hf repos ls lists repositories by storage usage (2026-05-28)
- slug: hf-repos-ls-lists-repositories-by-storage-usage-0fe62d0e8673
- score: 0.96

How to use it:

When inspecting Hub repositories and storage usage, run `hf repos ls`; add filters for the repositories you need, and use `--limit 0` to include all results. Use `--format json` when scripting or `-q` for IDs only.

Examples:

```
hf repos ls
```

```
hf repos ls --namespace <org> --type dataset --search <query> --limit 0 --format json | jq '.[].id'
```

```
hf repos ls -q
```

- why_it_matters: Inspect Hub repositories and their storage usage while reviewing or maintaining repository assets.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.17.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.17.0/docs/source/en/guides/cli.md>, <https://github.com/huggingface/huggingface_hub/blob/v1.17.0/src/huggingface_hub/cli/repos.py>
- gotchas: "Version: v1.17.0"; "--namespace <org>: Organization name; if omitted, lists repositories for the authenticated user."; "--type <model|dataset|space|bucket>: Filter by repository type. The docs do not say these values are mutually exclusive."; "--search <query>: Search repository names."; "--limit <integer>: Set the maximum number of results; default is 30, and 0 lists all results."; "--format <value>: Choose output format: `auto` (default), `human`, `agent`, `json`, or `quiet`."; "-q, --quiet: Equivalent to `--format quiet`; prints IDs only, one per line."; "Prerequisite: Install the `hf` CLI; the docs list the standalone installer, `huggingface_hub` package, and Homebrew. The CLI is included with `huggingface_hub`."; "Prerequisite: To list the authenticated user's repositories, authenticate with `hf auth login`; the docs do not specify a required token scope for listing."; "The default limit is 30."; "Results include models, datasets, spaces, and buckets, with storage size and percentage of namespace total, sorted by storage usage."

### hf spaces ssh opens a Dev Mode SSH session (2026-05-28)
- slug: hf-spaces-ssh-opens-a-dev-mode-ssh-session-504ba9065eb8
- score: 0.98

How to use it:

For debugging or inspecting a Space, run `hf spaces ssh <owner>/<space>` to connect to its Dev Mode container; if Dev Mode is off, the CLI prompts to enable it. Use `--dry-run` to print the SSH command or `-i <path>` to forward a specific identity file.

Examples:

```
hf spaces ssh <owner>/<space>
```

```
hf spaces ssh <owner>/<space> --dry-run
```

```
hf spaces ssh <owner>/<space> -i <identity-file-path>
```

- why_it_matters: Debug or inspect a Space's Dev Mode container over SSH.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.17.0>, <https://huggingface.co/docs/huggingface_hub/guides/cli>, <https://huggingface.co/docs/huggingface_hub/main/en/package_reference/cli>, <https://huggingface.co/docs/hub/en/spaces-dev-mode>
- gotchas: "Version: v1.17.0"; "SPACE_ID (required): Space ID, such as `<owner>/<space>`."; "--dry-run: Print the SSH command instead of running it."; "-i, --identity-file PATH: Identity file path forwarded to `ssh -i`."; "--auto: Enable Dev Mode without prompting if it is not already enabled."; "Prerequisite: Dev Mode must be running on the Space; the CLI prompts to enable it if disabled."; "Prerequisite: Register your SSH public key in Hugging Face user settings before connecting."; "The SSH session connects to a Space's Dev Mode container."; "If Dev Mode is not enabled, the CLI prompts to enable it."; "The SSH public key must be registered in HF user settings."

### hf CLI tables support --no-truncate (2026-05-21)
- slug: hf-cli-tables-support-no-truncate-de00188ba5c8
- score: 0.97

How to use it:

When scalar values are shortened in human-mode tables, run `hf models ls --no-truncate` to display them in full. For list- or dict-valued columns, use `--format json`.

Examples:

```
hf models ls --no-truncate
```

```
hf models ls --format json
```

- why_it_matters: Inspect long scalar values in human-mode CLI table output.
- before: Inspect scalar values in human-mode tables with their `...` shortening, or use the available output format for details.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.16.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.16.0/docs/source/en/guides/cli.md>
- gotchas: "Version: v1.16.0"; "--no-truncate: Global formatting flag; shows full scalar values in human tables. List- and dict-valued columns stay shortened."; "--format <value>: Global formatting flag. Accepted values: `auto`, `human`, `agent`, `json`, `quiet`; choose `json` to show list- and dict-valued columns in full. Docs do not state these options are mutually exclusive; they say mixing two output-mode flags raises a usage error."; "List- and dict-valued columns remain shortened in human mode because they can be arbitrarily long; use `--format json` for those."

### hf skills list shows marketplace skills and installation locations (2026-05-15)
- slug: hf-skills-list-shows-marketplace-skills-and-installation-locations-aee46a2e2af7
- score: 0.96

How to use it:

Before adding a Hugging Face marketplace skill, run `hf skills list` (alias `ls`) to see available skills and installation status. Then add the selected skill with `hf skills add [NAME]` and the desired location options.

Examples:

```
hf skills list
```

```
hf skills add <skill-name>
```

```
hf skills add <skill-name> --claude --global
```

- why_it_matters: Check which Hugging Face marketplace skills are available and whether they are installed before adding one.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.15.0>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.15.0"; "hf skills list: --token TEXT: User access token for listing marketplace skills."; "hf skills add: NAME: Marketplace skill name; the default `hf-cli` skill is generated locally."; "hf skills add: --claude: Install for Claude; the docs say the skill is also symlinked into Claude’s legacy skills directory."; "hf skills add: -g, --global: Install at user level instead of the current project directory."; "hf skills add: --dest PATH: Install into a custom skills directory."; "hf skills add: --force: Overwrite existing skills in the destination."; "Prerequisite: The `hf skills list` command was introduced in huggingface_hub v1.15.0."; "Installation status is shown for four supported locations: project, global, project Claude, and global Claude."

### hf spaces secrets and variables add, list, and delete (2026-05-06)
- slug: hf-spaces-secrets-and-variables-add-list-and-delete-c1e3ed49b3ac
- score: 0.96

How to use it:

When setting or inspecting a Space’s environment values, use `hf spaces secrets` for write-only secrets and `hf spaces variables` for readable variables. Add values with repeated `-s`/`-e` or the corresponding file option, list them with `ls`, and delete a key with `--yes` to skip confirmation.

Examples:

```
hf spaces secrets ls <owner>/<space>
hf spaces secrets add <owner>/<space> -s <KEY>=<VALUE> -s <KEY>=<VALUE>
hf spaces secrets add <owner>/<space> --secrets-file <path>
hf spaces secrets delete <owner>/<space> <KEY> --yes
```

```
hf spaces variables ls <owner>/<space>
hf spaces variables add <owner>/<space> -e <KEY>=<VALUE> -e <KEY>=<VALUE>
hf spaces variables add <owner>/<space> --env-file <path>
hf spaces variables delete <owner>/<space> <KEY> --yes
```

```
from huggingface_hub import HfApi
api = HfApi()
secrets = api.get_space_secrets(repo_id="<owner>/<space>")
```

- why_it_matters: Set or inspect a Space’s environment values while developing or maintaining its code.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.14.0>, <https://github.com/huggingface/huggingface_hub/pull/4170>, <https://github.com/huggingface/huggingface_hub/pull/4182>, <https://github.com/huggingface/huggingface_hub/blob/v1.14.0/docs/source/en/guides/cli.md>, <https://github.com/huggingface/huggingface_hub/blob/v1.14.0/docs/source/en/guides/manage-spaces.md>, <https://github.com/huggingface/huggingface_hub/blob/v1.14.0/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.14.0"; "SPACE_ID (required): Space ID, such as `<owner>/<space>`."; "KEY (required): Name of the secret or variable to remove."; "-s, --secrets: Set secret environment variables; accepts a key-value pair or a key whose value is read from the environment. Repeat to set multiple secrets."; "--secrets-file: Read secret environment variables from a file."; "-e, --env: Set environment variables using `KEY=VALUE`; repeat to set multiple variables."; "--env-file: Read environment variables from a file."; "-y, --yes: Automatically answer Yes to the delete confirmation prompt."; "--token: User Access Token for Hub authentication."; "repo_id (required): Space ID passed to `HfApi.get_space_secrets()`."; "Prerequisite: For CLI token authentication, `--token` accepts a User Access Token."; "Secret values are write-only and cannot be read back; listing returns keys, descriptions, and update timestamps."; "Variables are readable."; "The source gives `-env-file` in the release summary and `--env-file` in the CLI documentation."; "Docs conflict: The release summary says `-env-file`; v1.14.0 CLI docs document `--env-file` for variables."

### hf CLI global output formatting flags apply to every command (2026-04-30)
- slug: hf-cli-global-output-formatting-flags-apply-to-every-command-f880c917a004
- score: 0.97

How to use it:

When a script needs structured or ID-only output from an `hf` command, add `--json` or `-q`/`--quiet`; `--format auto` selects `human` in an interactive terminal and `agent` when invoked by an AI agent. The documented formatting guide says most commands accept these global flags.

Examples:

```
hf models ls --search bert --limit 2 --json | jq '.[].id'
```

```
hf collections ls --owner nvidia -q
```

```
hf <command> --format auto
```

- why_it_matters: When scripting Hub CLI commands from a coding workflow, request JSON or quiet output without checking whether each command declares those options.
- before: Check each command for individually declared `--format`, `--json`, or `-q` / `--quiet` options before using them.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0>, <https://huggingface.co/docs/huggingface_hub/main/guides/cli#output-formatting>, <https://huggingface.co/docs/huggingface_hub/main/guides/cli>
- gotchas: "Version: v1.13.0"; "--format <value>: Select output format: `auto` (default), `human`, `agent`, `json`, or `quiet`."; "--json: Equivalent to `--format json`; print structured JSON for scripting."; "-q, --quiet: Equivalent to `--format quiet`; print IDs one per line."; "--search <text>: Filter the models listing by search text; used in the documented example."; "--limit <number>: Limit the models listing; used in the documented example."; "--owner <owner>: Select the owner for the collections listing; used in the documented example."; "Prerequisite: Install the `hf` CLI; the guide says it is shipped with `huggingface_hub` and documents `pip install -U \"huggingface_hub\"`."; "Prerequisite: The guide notes that authentication is needed for some Hub interactions, such as accessing private repositories or uploading; it does not state an authentication prerequisite for the listed read commands."; "Docs conflict: The current guide describes formatting flags as accepted by “most” `hf` commands, while the v1.13.0 release note says every command accepts them. The guide also says jobs commands may consume formatting flags wherever they appear; use `--` when passing those flags through to a script."

### hf datasets leaderboard shows benchmark model scores (2026-04-30)
- slug: hf-datasets-leaderboard-shows-benchmark-model-scores-250de89fd407
- score: 0.94

How to use it:

When comparing model results for a benchmark dataset, run `hf datasets leaderboard <dataset_id>` to view submitted model scores; add `--limit <integer>` to cap the results.

Examples:

```
hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5
```

- why_it_matters: When comparing model results for a benchmark dataset during code evaluation, inspect its submitted scores from the terminal.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0>, <https://huggingface.co/docs/huggingface_hub/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/package_reference/cli>
- gotchas: "Version: v1.13.0"; "DATASET_ID (required): Benchmark dataset ID."; "--limit INTEGER: Limit the number of results; default is 20."; "Prerequisite: The release note introduces this CLI command in huggingface_hub v1.13.0."

### hf models, datasets, and spaces card fetch repo READMEs (2026-04-30)
- slug: hf-models-datasets-and-spaces-card-fetch-repo-readmes-db31bef02963
- score: 0.98

How to use it:

When reviewing a Hub model, dataset, or Space, run the matching `hf … card <repo_id>` command to print its README; add `--metadata` for metadata, `--text` for prose, or `--metadata --format json` for JSON metadata. The documented card commands require the repo ID; metadata and text selection are mutually exclusive.

Examples:

```
hf models card <model_id>
```

```
hf datasets card <dataset_id>
```

```
hf spaces card <space_id>
```

- why_it_matters: When reviewing a Hub model, dataset, or Space while working on code, fetch its README and inspect the full card or just its metadata or prose.
- before: Use `hf download <repo_id> README.md` or curl to obtain the raw README; the release description says those approaches write to a file and do not split the card.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0>, <https://github.com/huggingface/huggingface_hub/pull/4118>, <https://huggingface.co/docs/huggingface_hub/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/v1.29.0/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.13.0"; "MODEL_ID / DATASET_ID / SPACE_ID (required): Hub repository ID for the model, dataset, or Space whose card to fetch."; "--metadata: Output only card metadata from YAML frontmatter."; "--text: Output only the card text body, without metadata. Mutually exclusive with `--metadata`."; "--format json: Formats output as JSON; the guide documents this with `--metadata` to output metadata as JSON."; "--token TEXT: User Access Token option for card commands."; "Docs conflict: The `v1.13.0` release evidence documents `--format json` for card commands, while the currently accessible package reference does not list that option for the model and dataset card commands. The versioned v1.13.0 documentation URLs were inaccessible; Space card syntax was available only in a later versioned guide."

### hf models, datasets, and spaces ls lists files by repo ID (2026-04-30)
- slug: hf-models-datasets-and-spaces-ls-lists-files-by-repo-id-dc7420cdb84b
- score: 0.98

How to use it:

When inspecting a Hugging Face Hub repository, pass its repo ID to `hf models ls`, `hf datasets ls`, or `hf spaces ls` to list files. Add `--tree`, `-R`, `-h`, or `--revision <revision>` to adjust the listing.

Examples:

```
hf models ls <owner>/<model> --tree -h
```

```
hf datasets ls <owner>/<dataset> -R -h
```

```
hf spaces ls <owner>/<space> --tree -R -h
```

- why_it_matters: When inspecting a Hub repository during code work, list its files and optionally view them recursively, as a tree, with human-readable sizes, or at a revision.
- before: Use `hf models ls`, `hf datasets ls`, or `hf spaces ls` to list repos; use `hf buckets ls <bucket_id>` to list files in a bucket.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0>, <https://github.com/huggingface/huggingface_hub/pull/4166>, <https://github.com/huggingface/huggingface_hub/blob/v1.13.0/docs/source/en/guides/cli.md>, <https://github.com/huggingface/huggingface_hub/blob/v1.13.0/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.13.0"; "REPO_ID: Model, dataset, or Space ID; when supplied, lists files in that repo. Without it, lists Hub repositories of that type."; "--tree: List files in tree format; applies only to file listings."; "-R, --recursive: List files recursively; applies only to file listings."; "-h, --human-readable: Show sizes in human-readable format; applies only to file listings."; "--revision TEXT: Select a Git revision by branch name, tag, or commit hash."; "Prerequisite: Install the `hf` CLI; it is included with `huggingface_hub` or can be installed with the standalone installer. The docs do not state an auth prerequisite for public repo file listings."

### hf spaces pause, restart, and update settings from the CLI (2026-04-30)
- slug: hf-spaces-pause-restart-and-update-settings-from-the-cli-6909ef461bf6
- score: 0.98

How to use it:

When maintaining a Space, pause or restart it with `hf spaces pause` or `hf spaces restart`; use `--factory-reboot` for a clean rebuild. Update idle sleep time or hardware with `hf spaces settings`; `--sleep-time` requires upgraded hardware.

Examples:

```
hf spaces pause <owner>/<space>
```

```
hf spaces restart <owner>/<space> [--factory-reboot]
```

```
hf spaces settings <owner>/<space> [--sleep-time <seconds>] [--hardware <flavor>]
```

- why_it_matters: When maintaining a Space used in a coding workflow, pause it, restart it, or update its sleep time or hardware from the CLI.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0>, <https://github.com/huggingface/huggingface_hub/pull/4155>, <https://github.com/huggingface/huggingface_hub/blob/v1.13.0/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.13.0"; "SPACE_ID (required): Space ID, such as `<owner>/<space>`."; "--factory-reboot: Rebuild the Space from scratch without using the build cache."; "--sleep-time INTEGER: Idle time in seconds before the Space sleeps; `-1` means never. Only available on upgraded hardware."; "--hardware FLAVOR: Set the Space hardware flavor; run `hf spaces hardware` to list options. The release note shows it used together with `--sleep-time`."; "-y: Skip the pause or restart confirmation prompt."; "Prerequisite: `--sleep-time` is only available on upgraded hardware."; "`--sleep-time` is only available on upgraded hardware."; "Pausing or restarting tears down the Space container, so data on its ephemeral filesystem is lost. Mount a Volume or bucket with `hf spaces volumes set` to persist data across restarts."; "Docs conflict: The v1.13.0 CLI reference documents `--factory-reboot`, `--sleep-time`, and `--hardware`, but does not list `-y` under pause or restart options; the v1.13.0 release note says `-y` skips their confirmation prompt."

### huggingface_hub adds centralized hf:// URI and mount parsing (2026-04-30)
- slug: huggingface-hub-adds-centralized-hf-uri-and-mount-parsing-f234db8a14f9
- score: 0.92

How to use it:

When code accepts Hugging Face Hub locations or volume mount strings, parse locations with `parse_hf_uri` and mounts with `parse_hf_mount`. Call `.to_uri()` on each parsed value to emit its canonical string.

Examples:

```
from huggingface_hub import parse_hf_uri, parse_hf_mount

uri = parse_hf_uri("hf://datasets/<namespace>/<dataset>@refs/pr/3/train.json")
canonical_uri = uri.to_uri()

mount = parse_hf_mount("hf://buckets/<namespace>/<bucket>/sub/dir:/mnt:ro")
canonical_mount = mount.to_uri()
```

- why_it_matters: When maintaining code that accepts Hub locations or volume mount specifications, parse and round-trip their `hf://` strings with the library helpers.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.13.0>, <https://github.com/huggingface/huggingface_hub/pull/4158>, <https://github.com/huggingface/huggingface_hub/blob/v1.13.0/docs/source/en/package_reference/hf_uris.md>, <https://huggingface.co/docs/huggingface_hub/package_reference/hf_uris>
- gotchas: "Version: v1.13.0"; "uri (required): `parse_hf_uri` input. HF URI syntax is `hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]`; ID is `<namespace>/<name>`. Type prefix is optional for models; datasets, spaces, kernels, and buckets use plural prefixes. Revision is optional and applies to repos; path is optional."; "endpoint: A custom Hub endpoint used by `parse_hf_uri` to recognize web URLs on that endpoint; it has no effect on `hf://` URIs."; "mount_str (required): `parse_hf_mount` input; must start with `hf://` and include a mount path. Syntax: `hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]`."; "<MOUNT_PATH> (required): Absolute local mount path; must start with `/`."; ":ro | :rw: Optional read-only or read-write flag; the documented alternatives are mutually exclusive."; "Prerequisite: Use the v1.13.0-or-later `huggingface_hub` library version containing these helpers."; "Prerequisite: The helpers parse strings without network calls; no authentication setup is documented for parsing."; "The parsers are pure string parsers and make no network calls."; "The parser handles repo type prefixes, revisions, and paths and rejects invalid URI shapes."

### hf buckets list filters by name (2026-04-24)
- slug: hf-buckets-list-filters-by-name-dfabdf897846
- score: 0.97

How to use it:

When maintaining or debugging a workflow that stores checkpoints in buckets, pass `--search "checkpoint"` to `hf buckets list` to filter bucket names. The search string is optional; the CLI docs describe it as a search query.

Examples:

```
hf buckets list --search "checkpoint"
```

```
from huggingface_hub import list_buckets
for bucket in list_buckets(search="checkpoint"):
    print(bucket.id)
```

- why_it_matters: Find buckets by name while maintaining or debugging a repository workflow that stores checkpoints in buckets.
- before: List the buckets and filter them client-side.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.12.0>, <https://huggingface.co/docs/huggingface_hub/v1.20.1/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/package_reference/hf_api>
- gotchas: "Version: v1.12.0"; "--search TEXT: CLI search query for bucket listing."; "search: Optional string to filter bucket names in `list_buckets()`."; "Prerequisite: Python usage requires importing `list_buckets` from `huggingface_hub`."; "Search matches a name pattern."

### hf auth token prints the current token (2026-04-16)
- slug: hf-auth-token-prints-the-current-token-10b21dac729f
- score: 0.99

How to use it:

When you need the current Hugging Face token for a whoami-v2 request, pipe `hf auth token` into curl with a Bearer authorization header.

Examples:

```
hf auth token | xargs -I {} curl -H "Authorization: Bearer {}" https://huggingface.co/api/whoami-v2
```

- why_it_matters: Use the current Hugging Face token in a command that queries the whoami endpoint.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.11.0/docs/source/en/package_reference/cli.md>, <https://github.com/huggingface/huggingface_hub/blob/v1.11.0/src/huggingface_hub/cli/auth.py>
- gotchas: "Version: v1.11.0"; "hf auth token (required): Prints the current access token to stdout; has no documented options beyond --help."; "Authorization: Bearer {} (required): Passes the token from `hf auth token` as the request's Bearer credential."; "https://huggingface.co/api/whoami-v2 (required): Request URL shown in the release-note example."; "Prerequisite: Be logged in with a stored token; otherwise `hf auth token` errors and directs you to run `hf auth login` first."

### hf CLI uses --format and mode-aware confirmations (2026-04-16)
- slug: hf-cli-uses-format-and-mode-aware-confirmations-116ec8e5e1db
- score: 0.95

How to use it:

For migrated command groups, use `--format json` or `--format quiet` when scripts need machine-readable or minimal output; omit it for automatic mode selection. For confirmations, pass `--yes` in agent, JSON, or quiet mode; human mode prompts.

Examples:

```
hf cache ls --format json
```

```
hf cache ls --format quiet
```

```
hf cache rm <repo_id> --yes
```

- why_it_matters: Run hf CLI commands in scripts that need structured or minimal output and may delete repositories or cache entries.
- before: Use the old `--quiet` flags on migrated commands; confirmation prompts were not described as mode-aware.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md>, <https://huggingface.co/docs/huggingface_hub/main/guides/cli>
- gotchas: "Version: v1.11.0"; "--format <value>: Select output format; documented values are auto, human, agent, json, and quiet. `auto` is the default."; "--yes: Skip the confirmation prompt for `hf cache rm`. The v1.11.0 release note says agent, JSON, and quiet modes require it for confirmation prompts."; "<repo_id> (required): One or more cache targets may be repository IDs, Hub URIs, or revision hashes."; "Prerequisite: The `hf` CLI is shipped with `huggingface_hub`; official docs also provide standalone installation instructions."; "`jobs`, `buckets`, and `auth login/logout` are scheduled to follow in a future release; the spans do not state that they have migrated."; "Docs conflict: The v1.11.0 release note says `--yes` is required for confirmation prompts in agent, JSON, or quiet modes; the current CLI reference describes `--yes` as skipping the prompt but does not state that mode-specific requirement. Current docs may describe a later CLI version."

### hf spaces logs retrieves Space run and build logs (2026-04-16)
- slug: hf-spaces-logs-retrieves-space-run-and-build-logs-a31f50937bbc
- score: 0.98

How to use it:

When debugging a Space build failure or runtime crash, run `hf spaces logs <space_id>` for available run logs; add `--build` for build logs, `-f` to follow, or `-n <count>` to limit output to the last lines.

Examples:

```
hf spaces logs username/my-space
```

```
hf spaces logs username/my-space --build
```

```
hf spaces logs -f username/my-space
hf spaces logs -n 50 username/my-space
```

- why_it_matters: Debug a Space that fails to build or crashes at runtime.
- before: Open the browser to retrieve Space logs.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.11.0"; "SPACE_ID (required): Space ID, such as `username/repo-name`."; "--build: Fetch container build logs instead of run logs."; "-f, --follow: Stream log output until the server closes the stream; without it, print currently available logs."; "-n, --tail INTEGER: Number of lines to show from the end of the logs."

### hf spaces search adds semantic Space discovery (2026-04-16)
- slug: hf-spaces-search-adds-semantic-space-discovery-c6277921b6f1
- score: 0.99

How to use it:

When finding Spaces relevant to a repository task, describe the task in a natural-language query to search by what Spaces do. Run `hf spaces search` and add filters or output options as needed.

Examples:

```
hf spaces search "<natural-language query>" --limit 3
```

```
hf spaces search "<natural-language query>" --sdk gradio --description --json --limit 1
```

- why_it_matters: Find Spaces relevant to a repository task by describing what they do.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.11.0"; "QUERY (required): Natural-language search query describing what the Space does."; "--limit INTEGER: Maximum number of results; documented default is 10."; "--sdk TEXT: Filter results by SDK, such as gradio, docker, or static."; "--description: Show AI-generated descriptions."; "--json: Request JSON output; shown in the v1.11.0 release-note example. The current CLI reference does not list this option."; "Docs conflict: The current CLI reference does not list `--json` under `hf spaces search`, though the v1.11.0 release-note example uses it. The reference may describe a newer version; its documented search options include `--format` only in examples for other commands, not this command."

### hf spaces volumes lists, sets, and deletes Space volumes (2026-04-16)
- slug: hf-spaces-volumes-lists-sets-and-deletes-space-volumes-91611dfaff51
- score: 0.97

How to use it:

When updating a Space’s mounted volumes, use `hf spaces volumes ls` to inspect them, then `hf spaces volumes set` to replace the full list or `hf spaces volumes delete` to remove all volumes.

Examples:

```
hf spaces volumes ls <owner>/<space>
```

```
hf spaces volumes set <owner>/<space> -v hf://buckets/<owner>/<bucket>:/data
```

```
hf spaces volumes delete <owner>/<space>
```

- why_it_matters: Update mounted volumes while maintaining a Space from the command line.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.11.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.11.0/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.11.0"; "SPACE_ID (required): Space ID, such as `<owner>/<repo-name>`."; "-v, --volume TEXT: Mount one or more volumes using `hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]`; TYPE may be `models`, `datasets`, `spaces`, or `buckets`, and defaults to `models`. Models, datasets, and spaces are read-only; buckets are read-write by default. These TYPE values are alternatives, not documented as mutually exclusive across repeated volume options."; "--token TEXT: User Access Token."; "-y, --yes: For `delete`, automatically answer Yes to the prompt."

### hf buckets cp copies files into Buckets (2026-04-09)
- slug: hf-buckets-cp-copies-files-into-buckets-6651e642b6dc
- score: 0.99

How to use it:

When copying repository or Bucket data into a Bucket, run `hf buckets cp` with the source and destination `hf://` paths. The documented examples use a trailing slash on folder paths to copy their contents.

Examples:

```
hf buckets cp hf://buckets/<owner>/<source-bucket>/logs/ hf://buckets/<owner>/<destination-bucket>/logs/
```

```
hf buckets cp hf://datasets/<owner>/<dataset>/data/train/ hf://buckets/<owner>/<bucket>/datasets/train/
```

- why_it_matters: Copy a repository or Bucket data into a Bucket without downloading and re-uploading it.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.10.0>, <https://huggingface.co/docs/huggingface_hub/guides/buckets>, <https://huggingface.co/docs/hub/storage-buckets>
- gotchas: "Version: v1.10.0"; "source (required): First path; for this task, a repository or Bucket path. A trailing `/` copies the folder contents without nesting the folder itself."; "destination (required): Second path; for this task, the destination Bucket path."; "Prerequisite: Have read access to the source repository or Bucket and write access to the destination Bucket."; "Prerequisite: Remote-to-remote copies require the source and destination to be in the same storage region."; "Copying from a Bucket to a Repository is not yet supported."; "Xet-tracked files copy directly by hash; small text files not tracked with Xet are automatically downloaded and re-uploaded."

### hf CLI adapts selected command output for coding agents (2026-04-02)
- slug: hf-cli-adapts-selected-command-output-for-coding-agents-91ffed66479d
- score: 0.97

How to use it:

When an agent needs parseable output from a migrated `hf` command, rely on auto-detection or pass `--format agent`, `json`, or `quiet`. Use `agent` for untruncated TSV, `json` for structured output, or `quiet` for IDs only.

Examples:

```
hf models ls --limit 5 --format agent
```

```
hf models ls --search bert --limit 2 --json
```

```
hf models ls --limit 5 --format quiet
```

- why_it_matters: Inspect Hub models, datasets, Spaces, papers, or authentication details from a coding-agent workflow that needs parseable CLI output.
- before: The release note says output was designed for humans, with ANSI colors, padded tables, and truncated cells, making it harder for agents to parse.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.9.0>, <https://github.com/huggingface/huggingface_hub/pull/4015>, <https://huggingface.co/docs/huggingface_hub/main/guides/cli>, <https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.9.0"; "--format <value>: Select output format. Documented values: `auto` (default), `human`, `agent`, `json`, `quiet`. `auto` selects agent output when invoked by an AI agent; `agent` produces untruncated TSV, `json` structured JSON, and `quiet` IDs only. The docs do not say these values are mutually exclusive; they describe one selected format."; "--json: Alias for `--format json`."; "-q, --quiet: Alias for `--format quiet`; prints IDs one per line."; "--limit INTEGER: Limit the number of results returned."; "--search TEXT: Filter model list by search query."; "Prerequisite: Install the `huggingface_hub` package or the standalone `hf` CLI installer to use the CLI."; "Automatic detection and migrated output behavior are described for the listed commands; more commands are to be migrated later."

### hf Spaces volumes mount models, datasets, and buckets (2026-04-02)
- slug: hf-spaces-volumes-mount-models-datasets-and-buckets-e864193de58d
- score: 0.92

How to use it:

When a Space needs filesystem access to Hub models, datasets, or buckets, pass one or more `-v`/`--volume` values to `hf repos create` or `hf repos duplicate`. Use `hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]`; models, datasets, and Spaces mount read-only, while buckets are read-write by default.

Examples:

```
hf repos create <space-id> --type space --space-sdk <sdk> -v hf://<model-id>:/models -v hf://buckets/<owner>/<bucket>:/data
```

```
hf repos duplicate <source-space-id> <destination-space-id> --type space -v hf://<model-id>:/models -v hf://buckets/<owner>/<bucket>:/data
```

- why_it_matters: Configure a Space to access model, dataset, or bucket files through mounted filesystem paths.
- before: Use the deprecated persistent storage feature for Space storage.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.9.0>, <https://huggingface.co/docs/huggingface_hub/v1.9.0/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/v1.9.0/guides/repository>
- gotchas: "Version: v1.9.0"; "REPO_ID (required): Destination repo ID for `hf repos create`."; "--type space (required): Sets the repository type to Space; `--type` also accepts model or dataset."; "--space-sdk <sdk> (required): Sets the Space SDK; required when creating a Space."; "FROM_ID (required): Source repository ID for `hf repos duplicate`."; "[TO_ID]: Destination repo ID for `hf repos duplicate`; defaults to your namespace with the same repo name."; "-v, --volume TEXT: Repeat to mount volumes. Format: `hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]`. TYPE allows models, datasets, spaces, or buckets; it defaults to models when omitted. Models, datasets, and Spaces are always read-only; buckets are read-write by default. The `:ro` suffix selects read-only mounting. The docs do not describe volume values as mutually exclusive."; "Prerequisite: The CLI repository guide says the machine must be logged in and the user must own the repository or have write permission in its organization."; "Prerequisite: When creating a Space, provide its required SDK with `--space-sdk`."; "Volumes provide direct filesystem access to models, datasets, and storage buckets."; "Persistent storage is deprecated."

### hf jobs run mounts Hub repositories and Storage Buckets (2026-03-25)
- slug: hf-jobs-run-mounts-hub-repositories-and-storage-buckets-6495e0e21e79
- score: 0.97

How to use it:

When a job needs to query a Hub dataset from mounted files, mount the dataset at `/data` and run DuckDB against `/data/**/*.parquet`.

Examples:

```
from huggingface_hub import run_job, Volume

job = run_job(
    image="duckdb/duckdb",
    command=["duckdb", "-c", "SELECT * FROM '/data/**/*.parquet' LIMIT 5"],
    volumes=[Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")],
)
```

```
hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/data duckdb/duckdb duckdb -c "SELECT * FROM '/data/**/*.parquet' LIMIT 5"
```

- why_it_matters: Run a job that queries a Hub dataset directly from its mounted files.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.8.0>, <https://huggingface.co/docs/huggingface_hub/guides/jobs>, <https://huggingface.co/docs/huggingface_hub/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/main/package_reference/jobs>, <https://huggingface.co/docs/hub/en/jobs-configuration>
- gotchas: "Version: v1.8.0"; "run_job.volumes: List of `Volume` objects mounted in the job container."; "Volume.type (required): Volume type; `dataset` identifies a dataset repository."; "Volume.source (required): Source identifier, such as `HuggingFaceFW/fineweb`."; "Volume.mount_path (required): Absolute path inside the container; must start with `/`."; "-v, --volume: Mount a volume; Hub source format is `hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]`. Can be repeated. Dataset repos are mounted read-only."; "Prerequisite: Volume mounting requires `huggingface_hub` >= 1.8.0."; "Mounted volumes can access Hugging Face model, dataset, and Space repositories, as well as Storage Buckets."

### hf auth whoami supports JSON format (2026-03-20)
- slug: hf-auth-whoami-supports-json-format-ae445463ede5
- score: 0.95

How to use it:

When a script needs the authenticated Hugging Face identity as JSON, run `hf auth whoami --format json`.

Examples:

```
hf auth whoami --format json
```

- why_it_matters: Check the authenticated identity in a script that consumes JSON output.
- before: The command printed the username and organizations in its default human-readable output.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.7.2>, <https://github.com/huggingface/huggingface_hub/blob/v1.7.2/src/huggingface_hub/cli/auth.py>, <https://github.com/huggingface/huggingface_hub/blob/v1.7.2/docs/source/en/guides/cli.md>
- gotchas: "Version: v1.7.2"; "--format json: Selects JSON output; the command’s default format is table."; "Prerequisite: A locally available Hugging Face token is needed to retrieve the authenticated identity; if no token is found, the command reports “Not logged in” and exits."; "Prerequisite: Install the CLI, for example with `pip install -U huggingface_hub`."; "Docs conflict: The v1.7.2 CLI guide says `hf auth whoami` has no options, but the same-version CLI reference and source define `--format`; the source shows the JSON option is implemented."

### hf auth login supports --force re-login (2026-03-12)
- slug: hf-auth-login-supports-force-re-login-d880ee9aeeba
- score: 0.98

How to use it:

When already logged in and you need to switch tokens, run `hf auth login --force` to start the login flow again. Without `--force`, login skips when already logged in.

Examples:

```
hf auth login --force
```

- why_it_matters: Switch the Hugging Face token used for repository work when already logged in.
- before: Previously, `hf auth login` skipped the login flow when already logged in; the v1.7.0 release note describes `--force` as the way to explicitly go through it again.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.7.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.7.0/src/huggingface_hub/cli/auth.py>
- gotchas: "Version: v1.7.0"; "--force: Force re-login even if already logged in; defaults to false."; "Prerequisite: Login uses a token from huggingface.co/settings/tokens."; "The force flag is for explicitly going through the full login flow again."

### hf models ls filters by parameter count (2026-03-12)
- slug: hf-models-ls-filters-by-parameter-count-013a2c23af17
- score: 0.98

How to use it:

When you need Hub models within a parameter-count range, pass that range to `hf models ls --num-parameters`. Use the documented Hub UI range syntax, for example `min:6B,max:128B`.

Examples:

```
hf models ls --num-parameters min:6B,max:128B
```

```
models = hf_api.list_models(num_parameters="min:6B,max:128B")
```

- why_it_matters: Find models in the Hub within a parameter-count range for a repository dependency or evaluation.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.7.0>, <https://github.com/huggingface/huggingface_hub/pull/3897>, <https://huggingface.co/docs/huggingface_hub/v1.7.0/en/package_reference/cli>, <https://huggingface.co/docs/huggingface_hub/v1.7.0/en/guides/search>
- gotchas: "Version: v1.7.0"; "--num-parameters TEXT: Filter models by parameter count; accepts the Hub UI range syntax, such as `min:6B,max:128B`."; "num_parameters: Filter models by parameter count using the Hub UI range syntax."; "The filter uses the Hub UI/API range syntax."

### hf skills add installs to the default skills directory (2026-03-12)
- slug: hf-skills-add-installs-to-the-default-skills-directory-3772b2196898
- score: 0.97

How to use it:

When installing the hf-cli skill for the current project, run `hf skills add`; use `--global` for the user-level directory. Add agent flags to symlink the skill into the selected agent’s skills directory.

Examples:

```
hf skills add
```

```
hf skills add --global
```

```
hf skills add --claude --cursor
```

- why_it_matters: Install the hf-cli skill for the default agents directory in a repository or for the user account.
- before: Specify an installation destination or agent flags to install the skill.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.7.0>, <https://github.com/huggingface/huggingface_hub/pull/3923>, <https://huggingface.co/docs/huggingface_hub/v1.7.0/en/package_reference/cli>
- gotchas: "Version: v1.7.0"; "Requires Run `hf skills add` or `hf skills add --global`."; "--global / -g: Install globally at user level instead of in the current project directory."; "--claude: Install for Claude; custom agent selection symlinks the skill to that agent’s skills directory."; "--codex: Install for Codex; custom agent selection symlinks the skill to that agent’s skills directory."; "--cursor: Install for Cursor; custom agent selection symlinks the skill to that agent’s skills directory."; "--opencode: Install for OpenCode; custom agent selection symlinks the skill to that agent’s skills directory."; "--dest PATH: Install into a custom destination (path to skills directory)."; "--force: Overwrite existing skills in the destination."; "Agent-specific symlinks are created when agent flags are provided."

### hf spaces dev-mode enables and disables Space development mode (2026-03-06)
- slug: hf-spaces-dev-mode-enables-and-disables-space-development-mode-09fa46b9e144
- score: 0.97

How to use it:

When iterating on a Space, enable dev mode to restart its application without stopping the Space container. Wait for readiness and follow the printed connection instructions; pass `--stop` to disable dev mode.

Examples:

```
hf spaces dev-mode <username>/<my-space>
```

```
hf spaces dev-mode <username>/<my-space> --stop
```

- why_it_matters: Iterate on a Space while restarting its application without stopping the Space container.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.6.0>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>, <https://huggingface.co/docs/hub/en/spaces-dev-mode>
- gotchas: "Version: v1.6.0"; "SPACE_ID (required): Space ID, for example `username/repo-name`."; "--stop / --no-stop: Stop dev mode; default is `--no-stop`."; "--token TEXT: User Access Token for authentication."; "Prerequisite: Dev Mode requires a PRO or Team & Enterprise plan."

### hf webhooks manages Hub webhooks (2026-03-06)
- slug: hf-webhooks-manages-hub-webhooks-6a87f133ef4b
- score: 0.91

How to use it:

When managing Hugging Face Hub webhooks from the terminal, use `hf webhooks` to list or inspect them, create or update them, enable or disable them, and delete them.

Examples:

```
hf webhooks ls
hf webhooks info <webhook_id>
```

```
hf webhooks create --url <https://example.com/hook> --watch <type:name>
hf webhooks update <webhook_id> --url <https://new-url.com/hook>
```

```
hf webhooks enable <webhook_id>
hf webhooks disable <webhook_id>
hf webhooks delete <webhook_id>
```

- why_it_matters: Manage Hub webhooks from the terminal while working with a repository's Hub integration.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.6.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.6.0/src/huggingface_hub/cli/webhooks.py>, <https://github.com/huggingface/huggingface_hub/blob/v1.6.0/docs/source/en/guides/cli.md>
- gotchas: "Version: v1.6.0"; "<webhook_id> (required): Webhook ID for info, update, enable, disable, or delete."; "--watch <type:name> (required): Item to watch; repeatable. The value uses `type:name` format."; "--url <url>: URL to send webhook payloads to; for creation, mutually exclusive with `--job-id`, and one of the two must be provided."; "--job-id <id>: Job ID to trigger instead of pinging a URL; for creation, mutually exclusive with `--url`, and one of the two must be provided."; "--domain <repo|discussions>: Domain to watch; repeatable and defaults to all domains."; "--secret <secret>: Optional secret used to sign webhook payloads."; "--token <token>: Token option accepted by the webhook commands to override authentication."; "Prerequisite: Install the `huggingface_hub` package to use the `hf` CLI; the CLI guide also documents standalone and `uvx` installation options."

### hf jobs ps filters by labels and negated conditions (2026-02-03)
- slug: hf-jobs-ps-filters-by-labels-and-negated-conditions-5978bc41462c
- score: 0.92

How to use it:

When reviewing Hub Jobs, use `hf jobs ps -a` with repeated `--filter` options to match status, command, or labels; use `!=` to exclude matches.

Examples:

```
hf jobs ps -a --filter status!=error
```

```
hf jobs ps -a --filter "command!=*train.py"
```

```
hf jobs ps -a --filter label=model=Qwen3-06B --filter label=dataset!=Capybara
```

- why_it_matters: When reviewing Hub Jobs used to run repository workflows, filter the job listing by status, command, or labels.
- before: The release note documents status and command filters using `=` before this change; label filtering and `!=` are the additions.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.4.0>, <https://github.com/huggingface/huggingface_hub/pull/3742>, <https://github.com/huggingface/huggingface_hub/blob/v1.4.0/docs/source/en/guides/cli.md>, <https://github.com/huggingface/huggingface_hub/blob/v1.4.0/src/huggingface_hub/cli/jobs.py>
- gotchas: "Version: v1.4.0"; "-a, --all: Show Jobs of all statuses; without it, the command shows running Jobs by default."; "-f, --filter <condition>: Filter by a condition in `key=value` form. Repeat the option to require multiple filters; documented label examples include `label=<key>` and `label=<key>=<value>`."; "!= operator: Negate a condition, including status, command, and label conditions."; "label filter condition: `label=<key>` matches a label without a specified value; `label=<key>=<value>` matches a key-value label. Filters are applied together; docs do not describe them as mutually exclusive."; "Prerequisite: Install the `hf` CLI; v1.4.0 docs say it is shipped with `huggingface_hub` and provide standalone and `uvx` installation options."; "Prerequisite: The Jobs CLI guide says to be logged in to manage Hub Jobs; login uses a Hugging Face user access token."

### hf jobs uv run supports multi-GPU launchers and local config files (2026-02-03)
- slug: hf-jobs-uv-run-supports-multi-gpu-launchers-and-local-config-files-223b5b98478a
- score: 0.95

How to use it:

When running multi-GPU training or passing a local config file through Hub Jobs, use `hf jobs uv run` with a supported distributed runner or put the config after the script as a script argument.

Examples:

```
hf jobs uv run --with torch -- torchrun <script.py>
```

```
hf jobs uv run --with accelerate -- accelerate launch <script.py>
```

```
hf jobs uv run [--with <package>] <script.py> <config-file>
```

- why_it_matters: When developing or testing multi-GPU training code through Hub Jobs, launch it with a supported distributed runner and pass a local config file alongside the script.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.4.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.4.0/docs/source/en/package_reference/cli.md>, <https://huggingface.co/docs/huggingface_hub/en/jobs-quickstart>
- gotchas: "Version: v1.4.0"; "SCRIPT (required): UV script to run; may be a local file or URL."; "SCRIPT_ARGS: Arguments for the script, following the script path."; "--with <package>: Run with the given package installed. Repeated use or mutual exclusivity is not specified in the cited docs."; "--flavor <flavor>: Select hardware flavor; defaults to `cpu-basic`. Use a GPU flavor for GPU training; `hf jobs hardware` lists available flavors."; "Prerequisite: Install the Hugging Face CLI and log in to a Hugging Face account before running Jobs."

### hf models, datasets, spaces, endpoints, and cache ls add format options (2026-02-03)
- slug: hf-models-datasets-spaces-endpoints-and-cache-ls-add-format-options-a9ae5fae5e1f
- score: 0.96

How to use it:

When a repository maintenance script consumes one of the supported `ls` listings, select JSON with `--format json` or print IDs only with `--quiet` (`-q`).

Examples:

```
hf models ls --format json
```

```
hf datasets ls --quiet
```

```
hf cache ls --format json
```

- why_it_matters: When consuming CLI listings in repository maintenance scripts, request JSON or ID-only output from a supported listing command.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.4.0>, <https://github.com/huggingface/huggingface_hub/pull/3735>, <https://github.com/huggingface/huggingface_hub/blob/v1.4.0/docs/source/en/package_reference/cli.md>
- gotchas: "Version: v1.4.0"; "--format [table|json]: Selects table or JSON output; defaults to table."; "-q, --quiet: Prints only IDs, one per line. Documentation does not state whether this can be combined with `--format`."

### hf skills add installs the hf-cli coding skill (2026-02-03)
- slug: hf-skills-add-installs-the-hf-cli-coding-skill-55a5199d3f93
- score: 0.95

How to use it:

When a repository uses Hugging Face CLI workflows with Claude Code, Codex, or OpenCode, run `hf skills add` with the matching assistant flag. Add `--global` for a user-level install or use `--dest <PATH>` for a custom skills directory.

Examples:

```
hf skills add --claude
```

```
hf skills add --claude --global
```

```
hf skills add --codex --opencode
```

- why_it_matters: When working with Claude Code, Codex, or OpenCode on a repository that uses Hugging Face CLI workflows, install the hf-cli skill for the assistant.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.4.0>, <https://github.com/huggingface/huggingface_hub/blob/v1.4.0/src/huggingface_hub/cli/skills.py>
- gotchas: "Version: v1.4.0"; "Requires hf skills add --claude, --codex, or --opencode; --global installs at user level and --dest PATH selects a custom skills directory."; "--claude: Install for Claude. At least one assistant flag or `--dest` is required; assistant flags can be combined."; "--codex: Install for Codex. At least one assistant flag or `--dest` is required; assistant flags can be combined."; "--opencode: Install for OpenCode. At least one assistant flag or `--dest` is required; assistant flags can be combined."; "-g, --global: Install globally at user level instead of in the current project."; "--dest <PATH>: Install into a custom skills directory. Mutually exclusive with assistant flags and `--global`."; "--force: Overwrite existing skills in the destination."; "Docs conflict: Current CLI reference no longer lists `--codex` or `--opencode` and says `--claude` is unnecessary; it describes newer behavior than v1.4.0. The v1.4.0 source documents all three assistant flags."

### hf jobs hardware lists available Jobs hardware options (2026-01-22)
- slug: hf-jobs-hardware-lists-available-jobs-hardware-options-0306dec32550
- score: 0.94

How to use it:

When choosing hardware for a Hugging Face Jobs task, run `hf jobs hardware` to list available options.

Examples:

```
hf jobs hardware
```

- why_it_matters: Inspect available Hugging Face Jobs hardware options when selecting hardware for a repository coding or test job.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.3.3>, <https://huggingface.co/docs/huggingface_hub/v1.3.3/en/package_reference/cli>
- gotchas: "Version: v1.3.3"; "--help: Show help and exit."

### hf jobs stats monitors running jobs (2026-01-08)
- slug: hf-jobs-stats-monitors-running-jobs-925b28e4e4de
- score: 0.92

How to use it:

When Hugging Face Jobs are running, use `hf jobs stats` to display their CPU, memory, network, and available GPU usage.

Examples:

```
hf jobs stats
```

```
hf jobs stats <job_id>
```

- why_it_matters: Monitor resource usage for running Hub jobs during a development run.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.3.0>, <https://huggingface.co/docs/hub/jobs-manage>, <https://huggingface.co/docs/huggingface_hub/en/package_reference/cli>
- gotchas: "Version: v1.3.0"; "[JOB_IDS]...: Job IDs (or `namespace/job_id`) to limit the displayed statistics to specified Jobs."; "--namespace TEXT: Namespace where the Job is running; defaults to the current user’s namespace."; "--token TEXT: User Access Token."

### hf models, datasets, and spaces discovery commands (2026-01-08)
- slug: hf-models-datasets-and-spaces-discovery-commands-59ef2a0a8201
- score: 0.96

How to use it:

When inspecting Hub repositories from the CLI, use `hf models`, `hf datasets`, or `hf spaces` with `ls` to discover entries and `info <ID>` to inspect one; use `hf repo` for repository management.

Examples:

```
hf models ls --author=Qwen --limit=10
hf models info Qwen/Qwen-Image-2512
```

```
hf datasets ls --filter "format:parquet" --sort=downloads
hf datasets info HuggingFaceFW/fineweb
```

```
hf spaces ls --search "3d"
hf spaces info enzostvs/deepsite
```

- why_it_matters: Inspect Hub models, datasets, or Spaces from the CLI while working on a repository.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.3.0>, <https://huggingface.co/docs/huggingface_hub/v1.3.0/en/guides/cli>, <https://huggingface.co/docs/huggingface_hub/v1.3.0/en/package_reference/cli>
- gotchas: "Version: v1.3.0"; "MODEL_ID (required): Model ID, e.g. `username/repo-name`."; "DATASET_ID (required): Dataset ID, e.g. `username/repo-name`."; "SPACE_ID (required): Space ID, e.g. `username/repo-name`."; "--author TEXT: Filter by author or organization."; "--limit INTEGER: Limit the number of results; documented default is 10."; "--filter TEXT: Filter by tags; can be used multiple times. The docs do not specify the `format:parquet` syntax."; "--sort: Sort results. Dataset sort choices include `downloads`."; "--search TEXT: Search query."; "Prerequisite: The `hf` CLI is built into the `huggingface_hub` Python package."

### hf repo info includes an --expand parameter (2026-01-08)
- slug: hf-repo-info-includes-an-expand-parameter-c5400f1ab731
- score: 0.90

How to use it:

When inspecting a Hub repository, use `hf repo info` with `--expand` to request expanded repository information. The v1.3.0 CLI reference does not document this command or its arguments.

- why_it_matters: Inspect a repository using `hf repo info` when working with a Hub repository.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.3.0>
- gotchas: "Version: v1.3.0"

### Standalone installer can install the Transformers CLI (2026-01-08)
- slug: standalone-installer-can-install-the-transformers-cli-9c906dde70ac
- score: 0.96

How to use it:

When installing both CLIs, pass the platform’s Transformers option to the standalone installer. Then run `transformers` directly.

Examples:

```
curl -LsSf https://hf.co/cli/install.sh | bash -s -- --with-transformers
```

```
powershell -c "irm https://hf.co/cli/install.ps1 | iex" -WithTransformers
```

```
transformers serve
```

- why_it_matters: Install the Transformers CLI alongside the hf CLI in a development environment.
- sources: <https://github.com/huggingface/huggingface_hub/releases/tag/v1.3.0>, <https://github.com/huggingface/huggingface_hub/pull/3666>, <https://github.com/huggingface/huggingface_hub/blob/v1.3.0/utils/installers/install.sh>
- gotchas: "Version: v1.3.0"; "Requires Run the standalone installer with `--with-transformers` (bash) or `-WithTransformers` (PowerShell)."; "--with-transformers: Bash installer option to install the Transformers CLI alongside `hf`."; "-WithTransformers: PowerShell installer switch to install the Transformers CLI alongside `hf`."