Skip to main content
Download Hugging Face Hub files into the workspace and upload files or directories as a single commit. Mirage also supports repository creation, tags and file deletion using the official hf vocabulary.

Setup

Create a token using Hugging Face setup. Import HF from @struktoai/mirage-node. hf-buckets is a separate storage backend.
No service mount is required. For YAML and multiple accounts, see the CLI overview.

SKILL.md

The SKILL.md an agent reads with hf installed.
Available commandsThese commands are registered with this shell; --help after a command or subcommand shows its usage.hf

Supported commands

Run hf <command> --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Usage

Download, edit and upload

/work must be a writable workspace mount. Each upload is one commit, including all files selected from a directory. --repo-type selects models, datasets or spaces; --revision selects a branch, tag or commit. Local paths resolve against the shell’s working directory. With no source, hf upload acme/model reads ./model. Downloads, uploads and cache files use workspace operations rather than the host filesystem.

Repositories and tags

For spaces, use --repo-type space and --space_sdk. --exist-ok accepts an existing repository. Deleting matching files creates one commit.

Select files and cache downloads

--include, --exclude, --delete and repo-files delete use Hub glob semantics: * crosses /, [!a] negates a character class, and a trailing / names a folder. Directory uploads exclude .git and .cache/huggingface. Single-file uploads ignore the include/exclude/delete filters with warnings. Deletion globs match the remote listing; --delete is relative to the upload destination and spares files re-added by the same commit. .gitattributes is never deleted. An empty change is skipped with a warning. Without --local-dir, downloads use the cache layout under --cache-dir:
A branch or tag download writes its ref; a commit-pinned download does not. --force-download refetches a blob. Relative cache paths, including HF_HUB_CACHE and HF_HOME, resolve against the session’s working directory.

Behavior

The model, dataset and space VFS adapters expose remote repository files without creating a local checkout. They are read-only. Use a writable mount for editing and hf upload to choose the commit boundary. There is no interactive auth login or auth logout; the registered config supplies the token. Only the listed commands are implemented.

License

See compatibility and licenses.