Hugging Face CLI for coding agents

A coding agent can use the hf command-line interface to download a file from Hugging Face Hub into its working directory. The Hub is Hugging Face’s online repository for models, datasets, and related files. An agent can then inspect a downloaded file with local tools, such as a JSON parser.

The CLI is Hugging Face’s general tool for working with the Hub, including from coding agents. For example, an agent can fetch a model’s configuration file before adjusting code that reads it. The commands below follow Hugging Face documentation and have not been installed or tested for this article. See the Hugging Face CLI documentation for the full command guide.

Install and authenticate

Hugging Face recommends its standalone installer. On macOS and Linux, run:

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

The installer also adds the hf-cli agent skill globally, for Claude Code and other agents that read ~/.agents/skills. Hugging Face’s guide for AI agents explains the skill and how to leave it out with --exclude-skill. The CLI also ships with the huggingface_hub Python package, so pip install -U huggingface_hub installs it too. Install the CLI on the machine or in the environment where the agent will run hf. To check which commands that installation provides, run:

hf --help

You can download public files without logging in. To download files from a private repository or a gated repository, where Hugging Face restricts access, you need a Hugging Face token and permission to access the requested files.

Run hf auth login in the environment where the agent will run. By default, it starts a browser sign-in. It prints a URL and a short code, and it saves an access token on the machine after you approve. You can also paste a User Access Token from your Hugging Face settings instead. When an AI agent runs the command, the CLI does not prompt. It prints the URL and code for the agent to pass on to you and waits until you approve. Hugging Face says scripts and libraries that use the Hub can use the saved token when they make requests. Hugging Face suggests a read token unless you need to create or edit a repository. Keep the token out of the agent prompt and source files, and make sure the agent’s execution environment can access the stored credentials. See the authentication quickstart.

Download and inspect a public file

For a read-only task, an agent can download a model configuration and inspect its JSON locally. The following example uses the public gpt2 repository:

hf download gpt2 config.json --local-dir ./hf-example
python -m json.tool ./hf-example/config.json

The first command contacts Hugging Face Hub and saves config.json in ./hf-example without changing the Hub repository; the second formats the saved file as JSON and prints it locally. The exact contents depend on the revision the Hub serves.

Without --local-dir, the CLI saves files in the Hugging Face cache and prints the file’s path on the last line. With --local-dir, the file goes to that folder, and the CLI keeps a small .cache/huggingface/ metadata folder there so it does not download unchanged files again. For reproducible work, pass a branch, tag, or full commit hash with --revision; a commit hash identifies an exact repository state, while a branch name can point to newer content over time. Check hf download --help for the available syntax and options.

This example downloads one metadata file, not model weights. Fetching weights can consume substantial disk space and network bandwidth, so have the agent check which files it needs before requesting them. hf download has a --dry-run option that lists the files it would download and their sizes without downloading them.

Use the CLI for Hub inventory

hf also has listing commands for models and datasets, among other Hub resources. For example, an agent can use a listing command to find repositories that might fit its needs, review the results, and then decide what to download. Most hf commands share the same output flags. --json prints JSON, and -q prints only IDs, one per line. In its default auto mode, the CLI uses tab-separated output without truncation when it detects an AI agent. This search lists at most two models as JSON:

hf models ls --search bert --limit 2 --json

A realistic prompt for the example is:

Download config.json from the public gpt2 repository into ./hf-example. Format the local JSON so I can inspect it. Do not upload files or change anything on Hugging Face Hub.

The prompt tells the agent where to save the file and limits its work to downloading and inspecting it locally. The agent still needs network access for the download. A private or gated file also requires the account running hf to have access; the CLI cannot grant repository access on its own.