Downloading with the HF CLI

Why a CLI beats a browser for archival work

A browser download is a click and a prayer: no authentication context beyond your session, no pattern control (you get what the page serves), no retry semantics you can reason about, and a Downloads folder as the destination. For artifacts measured in gigabytes and acquisitions you intend to verify, you want a tool that speaks the hub's API natively: the official CLI — hf (the newer command; older material says huggingface-cli) — which understands revisions, resumes, rate limits, and file patterns.

The commands that matter for acquisition:

Download a whole snapshot: hf download <org/model> — the repository's current state, all files, into the local cache, with the path printed at the end.
Pin a revision: hf download <org/model> --revision <sha> — the frozen object you recorded during reconnaissance, immune to whatever main has become since.
Filter by pattern: --include "*.safetensors" --exclude "*.bin" — take the format generation you chose, skip the pickle-era leftovers.
Choose a destination: --local-dir <path> — land directly in your archive layout instead of the cache.
Authenticate when required: hf auth login for gated models — the token rides with the tool, not your browser.

What the tool gives you that the browser cannot

Three behaviors are quietly load-bearing. Resume: interrupted downloads pick up rather than restart (next lesson's theme). Verification-aware paths: the cache layout is content-addressed, so a re-run that finds everything present is a fast no-op rather than a re-download — idempotent acquisition. Rate-limit honesty: when the hub throttles, the CLI reports it instead of serving you a truncated success, and waiting or authenticating becomes an informed decision.

One caution: the cache is a cache. It lives where your user data lives, gets cleaned when disk pressure demands, and its internal layout is the tool's business. For the archive, --local-dir into your storage layout is the destination that matches ownership's first condition — bytes on storage you control, arranged the way your archive means something.

Acquire with the CLI; verify with your own hands. The tool moves bytes well, but your digest check after the transfer is what turns "the tool finished" into "I hold the artifact" — keep the two steps separate and both deliberate.

A complete acquisition invocation

Assembled from reconnaissance, the full archival download reads: pinned revision, chosen patterns, explicit destination. After it completes: size check, digest check against the pointer references, record. That sequence — recon, acquire, verify, record — is the integrity track's four-beat rhythm, and the CLI is only beat two.

Code

The archival acquisition, assembled·bash

# 0) From reconnaissance you hold: REPO, the pinned SHA, file patterns
REPO=<org/model>
SHA=<pinned-revision-sha>

# 1) Authenticate once, if the model is gated
hf auth login

# 2) The acquisition: pinned, filtered, direct to your archive layout
hf download "$REPO" \
  --revision "$SHA" \
  --include "*.safetensors" "*.json" "*.txt" \
  --exclude "*.bin" "*.pth" \
  --local-dir ~/models/$(basename $REPO)

# 3) Verify (beats 2-3 of the rhythm — sizes then digests)
cd ~/models/$(basename $REPO)
shasum -a 256 *.safetensors > SHA256SUMS.acquired
# compare each line against the pointer references from the
# previous lesson; any mismatch is a finding, not a footnote.

# 4) Record: date, repo, sha, digests -> the acquisition note

Exercise

Perform one complete CLI acquisition of a small public model (a tokenizer-only repo or a tiny model, to keep it light): pin the revision, filter patterns, land in a directory you control, then run the verify beats. Write the acquisition note's four lines: repo, revision, digests, date.

Hint

Small on purpose — the exercise is the rhythm, not the gigabytes. If the repo has no safetensors, verify whatever large files it has against their pointer references; the mechanics are identical.

Why a CLI beats a browser for archival work

What the tool gives you that the browser cannot

A complete acquisition invocation

Code

External links

Exercise

Progress

Comments 0