Hugging Face CLI

Use hf for Hub operations from the shell. The CLI generates its own command skill from the installed version; this skill owns authentication, cache hygiene, and the authority boundary around uploads and paid jobs.

Workflow

1. Resolve the account: hf auth whoami; log in with hf auth login or pass HF_TOKEN through the environment. Never run hf auth token in a transcript or log.
2. Read before writing: hf models info <repo-id>, hf models card <repo-id>, hf models ls --sort downloads --limit 10, and the datasets and spaces twins answer most questions without a download; hf datasets sql queries a dataset's Parquet files with DuckDB in place.

3. Download into an ignored directory: gated repositories need the license accepted on the website first.

   hf download <repo-id> --local-dir models/<name>
   hf download <owner>/<dataset> --repo-type dataset --local-dir data/<name>

4. Inspect cache use before cleanup: hf cache ls and hf cache prune --dry-run show retained data and proposed deletions. Remove only recorded task-owned disposable entries after checking consumers: preview with hf cache rm <repo-id-or-revision> --dry-run, then rerun with --yes, because agent and non-interactive runs cannot answer its confirmation prompt; broad pruning of shared revisions or incomplete downloads requires explicit cleanup scope. HF_HOME relocates the cache for future operations.
5. Upload with authority: hf repos create <repo-id> --private then hf upload <repo-id> <local-path> --private; hf upload creates a missing repository with the account's default visibility unless --private is set. Confirm repository, visibility, and license before the first push, then verify with hf models info or hf repos ls. Buckets are public unless the organization's default is private: create them with hf buckets create <bucket> --private, preview hf sync with --dry-run, and pass --delete only when removing destination files is authorized.
6. Run remote compute with authority: hf jobs run and hf jobs uv run bill by hardware flavor; preview the resolved flavor, timeout, and volumes with --dry-run, then watch hf jobs logs and hf jobs ps. Pass secrets by name (--secrets HF_TOKEN reads the local environment), never as NAME=value, and never use --expose-public, which serves a port without authentication, unless that exposure is authorized. hf sandbox VMs run on Jobs and hf endpoints deploy creates hourly-billed Inference Endpoints, so they need the same authority; release what you started with hf jobs cancel, hf sandbox kill, or hf endpoints pause.

Gotchas

• Use hf, not huggingface-cli: hf replaced huggingface-cli; the mise tool is pypi:huggingface_hub.
• Size large transfers before downloading: inspect file selection and disk headroom before a download; use --include/--exclude when only part of a repository is needed, and hf download <repo-id> --dry-run to list the files, sizes, and total without downloading. Verify a downloaded revision with hf cache verify <repo-id> --revision <sha> (and --local-dir when used); add --fail-on-missing-files only when the complete revision was intended. This verifies downloaded bytes, not remote upload completion.
• Pin a revision: pass --revision <sha> for reproducible downloads; anything loaded with trust_remote_code is third-party code to review first.
• Pass --dest to hf skills add: without it, the command also symlinks each skill into .claude/skills (~/.claude/skills with --global), creating that directory in projects that lack it; since 2.3.0 it skips the link when that directory already resolves to .agents/skills.

Official Skills

Upstream: huggingface/skills. Follow the shared vendor-skill policy to review and install marketplace packages from an immutable snapshot. Native marketplace hf skills add <name> and unqualified hf skills update fetch mutable content without a revision pin; they do not implement that policy. Use native generation only for the hf-cli skill, which comes from the installed CLI, and review it before installing or refreshing at project scope:

hf skills list
hf skills preview                            # review the generated CLI skill
hf skills add --dest .agents/skills          # the CLI skill
hf skills update hf-cli --dest .agents/skills # refresh only the generated CLI skill

Documentation

• hf CLI guide · huggingface/skills
• Releases: huggingface_hub
• Companion skills: kaggle, colab, python-stack.