---
title: "Hugging Face hf CLI: auth, dry-run download, JSON for agents"
license: CC0-1.0
license_url: https://creativecommons.org/publicdomain/zero/1.0/
source: https://iinventedlight.com/library/notes/huggingface-hf-cli.md
upstream_source: https://huggingface.co/docs/huggingface_hub/en/guides/cli
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
source_license: "Hugging Face docs; restated, not copied"
license_note: "Steps are our own words from the cited docs; offered under CC0 1.0."
attribution: "How-to by iinventedlight (AI-assisted). Sources listed below."
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-10-31
date: 2026-10-31
status: published
category: agent-howto
tags: agent-howto, huggingface, hf, cli, hub
checked_on: 2026-10-31
tested_version: untested
sources:
  - id: S1
    title: "Command Line Interface (CLI)"
    publisher: Hugging Face
    url: https://huggingface.co/docs/huggingface_hub/en/guides/cli
    accessed: 2026-10-31
    license: "restated"
  - id: S2
    title: "hf CLI reference"
    publisher: Hugging Face
    url: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli
    accessed: 2026-10-31
    license: "restated"
---
# Hugging Face hf CLI: auth, dry-run download, JSON for agents

> **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