hf - Mirage

Act on the Hugging Face Hub in the official CLI’s vocabulary. A repo is a tree, so mirage already reads one as files: the hf_models, hf_datasets and hf_spaces mounts are the read half, and ls, cat and grep are how an agent explores one without downloading it. hf is the write half.

The three tiers

A Hub write is a commit, and a POSIX write cannot say where a commit ends, so the mount does not take one. That is the same split github and git already draw, and it gives three places rather than two:

Tier	What it does	Example
Hub mount	reads a remote repo, downloading nothing	`cat /m/config.json`
Local mount	holds the writable copy	`echo x > /work/f.txt`
`hf` CLI	moves between them, one commit per invocation	`hf upload acme/m /work/f.txt f.txt`

So editing a Hub file is download, edit, upload:

hf download acme/model config.json --local-dir /work
sed -i 's/1024/2048/' /work/config.json
hf upload acme/model /work/config.json config.json --commit-message "widen"

hf upload batches every file of one invocation into a single commit carrying the message the line gave it, which is exactly what a cp -r onto a mount could not express.

Install

import {
  HF,
  HfModelsResource,
  Mount,
  MountMode,
  RAMResource,
  Workspace,
} from '@struktoai/mirage-node'

const token = process.env.HF_TOKEN ?? ''
const ws = new Workspace({
  '/m': new HfModelsResource({ repoId: 'acme/model', token }),
  '/work': new Mount(new RAMResource(), { mode: MountMode.WRITE }),
})
ws.registerCli('hf', HF, { token })

await ws.execute('hf auth whoami')

/m keeps the default read mode, which is all a Hub mount can offer. /work is the mount that takes MountMode.WRITE, and that asymmetry is the workflow above rather than an oversight: the Hub half is read-only, the local half is where edits live. The Hub resources need no extra dependency: they speak the Hub API over the runtime’s own fetch. HfBucketsResource is a different product, the Xet object store behind HF Buckets.

Commands

Verb	What it does
`hf auth whoami`	the account the token names
`hf auth list`	the stored tokens
`hf repo create <id>`	create a repo; `--repo-type`, `--private`, `--space_sdk`, `--exist-ok`
`hf repo tag create\|list\|delete`	git tags on a repo
`hf repo-files delete <id> <glob>`	delete paths in one commit
`hf download <id> [file...]`	fetch to `--local-dir` or the cache
`hf upload <id> <local> [path]`	upload a file or directory as one commit
`hf env`, `hf version`	the endpoint and version in use

There is no hf auth login or logout, and that is deliberate rather than missing: the token comes from the config the embedding program registers, so there is nothing to log in to.

Downloads

--local-dir writes the files as themselves. Without it, hf download builds upstream’s cache layout under --cache-dir, byte for byte:

models--acme--model/
  blobs/<etag>
  refs/main                 ← only for a symbolic revision
  snapshots/<sha>/config.json → ../../blobs/<etag>

refs/<name> is written only when the revision is a branch or tag. A sha-pinned download writes no ref, which is what the real binary does. --revision takes a branch, a tag or a commit sha. --include and --exclude take globs, and --force-download refetches rather than reusing the cached blob.

Getting Started

AI Agents

Resources

CLIs

Watch

Runtimes

hf

The three tiers

Install

Commands

Downloads

​The three tiers

​Install

​Commands

​Downloads

The three tiers

Install

Commands

Downloads