Cli And Automation

CLI and Automation

Use this sub-skill when a researcher needs to select, explain, or safely automate the hf command-line interface. Treat the installed executable's --help as the release-specific authority: the generated CLI surface changes with the installed huggingface_hub version.

Trigger routes

Load this skill for:

• “what hf command/flag should I use?” and shell scripts around the Hub;
• human, JSON, quiet, or agent output, jq/pipeline parsing, or stderr hygiene;
• login, token selection, HF_TOKEN, auth state, or non-interactive operation;
• downloads, uploads, hf cp, bucket sync, URI/revision/type selection, or dry-run/plan/apply review;
• repos, branches, tags, models, datasets, Spaces, cards, search, papers, discussions, webhooks, cache, endpoints, buckets, Jobs, or sandboxes;
• trusted CLI extension install/update/remove/dispatch or extension authoring;
• hf skills add, update, preview, marketplace skills, or the implicit skill freshness check.

First route: establish the executable

Read CLI reference before using a detailed flag. Run only safe probes first:

bashCopy code
command -v hf && hf --help
hf version
hf --version

hf is the supported entry point. huggingface-cli is a deprecated entry point and may warn and exit instead of providing the old CLI. tiny-agents is a separate MCP/agent CLI, not an alias for hf; inspect it with tiny-agents --help and do not infer its syntax from this skill. If the commands resolve to different installations, report the paths and use the one intended by the current environment.

Safe operating loop

1. Classify the request as read-only, local-only, Hub mutation, or hosted compute. Ask for the target namespace/repo and permission when a mutation is intended; placeholders are not authorization.
2. Check hf <group> --help and then hf <group> <command> --help for the installed version. Do not copy a flag from an older generated reference without checking help.
3. Select an explicit output mode for scripts. Parse stdout only; keep stderr visible for warnings, hints, errors, and progress diagnostics.
4. Supply credentials through the environment or a supported secret-file mechanism. Never print, echo, log, commit, or put a token in a URL.
5. For movement or deletion, preview first (--dry-run, --plan, or a read-only list), inspect the exact target and action set, then obtain confirmation before applying.
6. Pin --repo-type/--revision or encode them in one hf:// URI. Never combine URI-encoded type/revision/path with duplicate positional/options.
7. Check exit status. For Jobs and Spaces, a streamed log ending is not proof of success; inspect or wait for the terminal status.
8. Record the command, selected version, output mode, target, and whether the operation was previewed. Redact credentials from logs.

Progressive disclosure

• Use CLI reference for the command catalog, verified flags, aliases, output semantics, URI rules, safety boundaries, and the skills/extensions surface.
• Use automation workflows for safe stdout/stderr pipelines, download dry runs, bucket plan/apply, job control, and mutation gates.
• Use API reference only when output or the lightweight Click-compatible framework explains a surprising CLI behavior.
• Use development when generated CLI docs, static imports, or release-surface drift is involved.
• Use troubleshooting for installation, auth, parsing, URI, network, extension, and generated-doc failures.
• Run the bundled read-only help checker when entry-point health or a bounded help smoke test is useful. It accepts only a trusted executable named hf, bounded timeouts/probe counts, and exact allowlisted built-in command paths with no arguments; every invocation ends in --help. It never invokes a mutating command and always disables startup update checks for its child processes.

Routing map

This sub-skill does not replace the sibling operating skills for detailed Python APIs, inference behavior, cache internals, or Hub mutation policy. It owns the CLI boundary and automation contract.

Non-negotiable safety rules

• An example that creates, uploads, deletes, changes visibility, changes a Space, manages a webhook, installs an extension/skill, launches compute, or applies a plan is a mutation. Use a clearly marked mutation example only after target and authorization are confirmed; prefer placeholders.
• --yes bypasses a confirmation gate; it does not make the target safe. Never add it merely to make a script non-interactive.
• --format json does not mean every command is non-interactive. In particular, login's browser/menu flow has restrictions; use an environment token for automation.
• hf auth token intentionally prints a secret. Treat it as a narrow, deliberate pipe, never as a diagnostic command.
• Do not use hf cp for local-to-local or unsupported bucket-to-repo copies; use the documented alternative. Do not pass a directory to single-file cp.
• hf skills preview produces generated target-side hf-cli/SKILL.md content. That generated file is distinct from this managed huggingface-hub/sub-skills/cli-and-automation/ skill; do not overwrite or present one as the other.

Verification targets

A useful route ends with observable evidence: help exits zero; stdout parses under the selected mode; stderr remains separate; a dry-run/plan reports the intended actions without payload mutation; refused confirmation exits non-zero; and a final status command verifies the operation. For the difficult synthetic case, use a fake CLI/API fixture or help-only invocation to exercise a hf download --dry-run --format json parse, preserve a warning on stderr, and prove that hf repos delete without --yes is refused before any delete API call. Broad production-marked native tests do not establish this end-to-end shell contract.