hf

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.

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 with hf cache rm <repo-id-or-revision> after checking consumers; 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.

6. Run remote compute with authority: hf jobs run and hf jobs uv run bill by hardware flavor; confirm the flavor and timeout, then watch hf jobs logs and hf jobs ps. 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 sandbox kill or hf endpoints pause.