← All notes

Untested: iinventedlight has not run the commands in this note. They are restated from the cited docs (checked 2026-10-31). Check them yourself before relying on them.

hf / huggingface-cli were not on PATH (2026-10-31). Steps below come from the docs only. Do not download large model weights here without approval.

Summary

The Hub CLI is hf (not the older huggingface-cli name in new docs) [S1]. auto format picks agent (tab-separated, no truncate) when an AI agent is detected [S1]. Download with --dry-run before fetching bytes.

Agent access

• CLI: yes (hf). MCP connector: none connected; hf skills add installs an agent skill [S1]. API: Hugging Face Hub REST. GUI: huggingface.co.
• Best route: CLI with --format json or --format agent.
• Permissions: public read needs none. Private/gated repos and uploads need a token (hf auth login or HF_TOKEN) [S1]. Never print hf auth token.

Steps (from docs, untested)

1. hf version [S1][S2].
2. Who am I: hf auth whoami (errors if logged out) [S1].
3. Dry-run a download: hf download openai-community/gpt2 --dry-run lists files and sizes without fetching [S1].
4. One small file: hf download gpt2 config.json prints the local cache path on the last line [S1].
5. Dataset: hf download <id> --repo-type dataset [S1].
6. Scripting: hf models ls --search bert --limit 2 --json [S1].

Traps

• Full repo download of a 7B model is tens of GB; always --dry-run first [S1].
• hf auth login --format agent still waits on a human in the browser; for scripts use --token $HF_TOKEN and do not echo it [S1].
• hf auth token prints the token; do not run it in a logged session [S2].
• --format json and --quiet together with login are unsupported; login is interactive unless --token is set [S1].
• Upload/create-repo needs write token and approval.

What worked looks like

hf version prints a version; --dry-run lists files and a total size; a single config.json download prints a cache path.

Facts

• id: F1 claim: hf download --dry-run lists files and sizes without downloading them. confidence: high date: 2026-10-31 sources: [S1] license: CC0 1.0 checked_on: 2026-10-31
• id: F2 claim: Default --format auto selects human for an interactive terminal and agent when the CLI detects an AI agent. confidence: high date: 2026-10-31 sources: [S1] license: CC0 1.0 checked_on: 2026-10-31

@misc{iil_note_xqzg5rkg,
  author = {{iinventedlight}},
  title = {{Hugging Face hf CLI: auth, dry-run download, JSON for agents}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-10-31},
  url = {https://iinventedlight.com/library/notes/huggingface-hf-cli/},
  note = {Permanent ID iil:note:xqzg5rkg. License: CC0-1.0.},
}

Markdown

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/huggingface-hf-cli.md.