Skip to content
Get packs

Guide · Agent skill

How to use the Hugging Face Hub CLI agent skill (hf-cli)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The hf-cli skill is an agent skill for the official hf command-line tool, which manages models, datasets, spaces, buckets and other content on the Hugging Face Hub. Once it is installed, your agent knows which hf commands and options exist, so you can ask in plain language instead of looking up flags. This guide explains what the skill does, how to install it, how to trigger it, and what to check before letting it upload or delete anything.

Hugging Face Hub CLIhuggingface/skills · Apache-2.0

Quick start

  1. 1Install the hf CLI. Run the install script from the skill's install line, after reviewing it. Then confirm the tool is available with hf version.
  2. 2Add the skill folder. Unzip the hf-cli ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  3. 3Log in. Ask the agent to log you in, or run hf auth login yourself, using a browser login or a token from huggingface.co/settings/tokens. Check the account with hf auth whoami.
  4. 4Make a read-only request first. Ask for a download or a listing before any upload. This confirms the network access and token work.
  5. 5Review before writing. For uploads, syncs or deletes, ask for a dry run or plan, then check the output before approving the change.

What an agent skill is and what hf-cli makes the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent instructions for one kind of task. When a request matches the skill, the agent reads those instructions and uses them to carry out the work.

The hf-cli skill is mostly a command reference. It tells the agent how to use the hf tool to log in, download and upload files, copy or sync folders with buckets, manage the local cache, and organize collections and jobs. The skill's notes say the hf command replaces the deprecated huggingface-cli, and the agent is directed to use the current hf syntax.

  • Authentication with hf auth commands such as hf auth whoami
  • Downloading and uploading models, datasets and other repo files with hf download and hf upload
  • Syncing local folders with buckets using hf sync
  • Managing the local cache with hf cache commands
  • Creating and organizing collections with hf collections commands

Install the hf CLI before the skill

The skill needs the hf command-line tool. The skill's own install line is a curl command that downloads an install script from hf.co and runs it with bash. Review the script before you run it, because the install runs code on your machine.

Install the hf CLI first, then install the skill.

curl -LsSf https://hf.co/cli/install.sh | bash -s

Install the hf-cli skill in Claude

Download the hf-cli ZIP from this page and unzip it. The skill folder contains SKILL.md. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

  • Personal install: ~/.claude/skills/hf-cli/
  • Project install: .claude/skills/hf-cli/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Trigger the skill with natural requests

You do not need to name the skill. The skill description tells the agent to use it when you mention hf, huggingface, Hugging Face, huggingface-cli or hugging face cli, or when you ask for something in the Hugging Face ecosystem. It also covers cloud storage needs such as training checkpoints, data pipelines or agent traces.

Be specific about the repo and the action. The agent can then choose the right command and check its options.

  • Log me in to Hugging Face with my access token and confirm which account I am using.
  • Download only the safetensors files from this model repo into ./models/my-model.
  • Show me the largest files in my Hugging Face cache and remove the ones I do not need.
  • Upload this folder to my private dataset repo with a commit message about the new split.
  • Sync my checkpoints folder with my bucket, but show me a dry run first.

Safety notes: scripts, network and changes to your account

The skill runs a shell install script and uses the network to reach the Hugging Face Hub. Logging in and the hf download and upload commands need network access. Private repos and write actions need an access token, which you can create at huggingface.co/settings/tokens.

Some commands change or publish files on your account. Upload and delete commands, hf sync with --delete, hf buckets remove, and hf cache rm can alter remote content or remove local files. Ask the agent for a --dry-run or --plan first where the command offers one, and review the target repo before approving an upload to a public repo.

  • Review the install script before running it.
  • Use --dry-run on hf download, hf cache rm and hf buckets remove when the command supports it.
  • Keep tokens private and use hf auth list to see what is stored.
  • Do not let the agent upload to a public repo without a review step.

What people use it for

  • Download a model or selected files from a Hub repo into a local folder for testing.
  • Upload a dataset folder to a private repo with a commit message and description.
  • Sync training checkpoints between a local folder and a Hugging Face bucket.
  • Clean up the local Hugging Face cache by listing, pruning or removing old revisions.
  • Create and update a collection of models and datasets for a project.

Frequently asked questions

Is the hf-cli skill free to use?

The source does not state a price or licence terms for the Hugging Face Hub itself. The skill listing shows an Apache-2.0 licence, so check that licence for the skill's own terms before you rely on it.

What do I need before I install hf-cli?

You need the hf command-line tool, installed with the curl install line in the skill. You also need network access to the Hugging Face Hub and a Hugging Face account with an access token for private repos or write actions.

How do I install the hf-cli skill in Claude?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Does hf-cli replace huggingface-cli?

Yes. The skill says the hf command replaces the deprecated huggingface-cli, and the agent should use the hf syntax. Auth commands now sit under hf auth, for example hf auth whoami.

Why won't my hf command work?

Check that the hf CLI is installed by running hf version, and that the install script finished without errors. For private repos, confirm you are logged in with hf auth whoami, since write actions need a valid token.

Can the agent delete things on my Hugging Face account?

Yes, some commands can remove or change content, such as hf buckets remove, hf buckets delete and hf collections delete. Ask for a dry run where available and review the target before approving.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use hf-cli if you already work with Hugging Face models, datasets or buckets and want an agent to handle logins, transfers and cache work without memorizing hf flags. Pick something else if you do not use Hugging Face at all, or if you need an agent to publish files without a human review step.

Download the skill