Neura Market Reference: Hugging Face Hub CLI (hf)

Overview

The hf command is the modern CLI for interacting with the Hugging Face Hub. It replaces the deprecated huggingface-cli and provides a unified interface for managing repositories, models, datasets, Spaces, Inference Endpoints, compute jobs, storage buckets, webhooks, collections, and more. This document covers every capability, procedure, parameter, constraint, and failure mode.

Installation and Setup

Installation

Install the CLI with a single command:

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

After installation, verify the tool with hf --help to see all functions and real-world examples.

Authentication

Authentication is required for most operations. You can authenticate in two ways:

• Set the HF_TOKEN environment variable with your access token.
• Use the --token flag with each command.

Tokens are obtained from huggingface.co/settings/tokens.

Manage authentication sessions with the hf auth subcommands:

• hf auth login – start a token-based session.
• hf auth logout – end the current session.
• hf auth list – view all stored tokens.
• hf auth switch – switch between stored tokens.
• hf auth whoami – identify the current account.

Environment and Version

View environment details or the CLI version:

• hf env – display environment information.
• hf version – display the CLI version.

Repository Management

All repository operations are under hf repos. The REPO_ID parameter (e.g., username/repo-name) is required for most commands.

• hf repos create – create a new repository.
• hf repos delete – delete a repository.
• hf repos duplicate – duplicate a repository to a new ID.
• hf repos move – move a repository between namespaces.
• hf repos branch – manage branches (Git-like references).
• hf repos tag – manage tags.
• hf repos delete-files – delete files using patterns.

File Operations

Downloading and Uploading Files

• hf download REPO_ID – download files from a repository.
• hf upload REPO_ID – upload files or folders. This command handles single-commit uploads and supports resumable uploads for large directories. Do not use the deprecated hf upload-large-folder REPO_ID LOCAL_PATH; use hf upload instead.
• hf sync – sync files between a local directory and a bucket.

Bucket Management

Full S3-like bucket operations:

• hf buckets create – create a bucket.
• hf buckets cp – copy files to/from a bucket.
• hf buckets mv – move files within a bucket.
• hf buckets rm – remove files from a bucket.
• hf buckets sync – sync a local directory with a bucket.

Local Cache Management

Manage the local cache:

• hf cache list – list cached items.
• hf cache prune – remove detached revisions from the cache.
• hf cache verify – verify checksums of cached files.

Data and Models

Datasets

Query and explore datasets:

• hf datasets list – list datasets.
• hf datasets info – get dataset information.
• hf datasets parquet – list parquet URLs for a dataset.
• hf datasets sql SQL – execute a raw SQL query against dataset parquet URLs using DuckDB (no separate install needed). Replace SQL with your query, e.g., 'SELECT * FROM dataset LIMIT 10'.

Models

• hf models list – list models.
• hf models info – get model information.

Daily Papers

• hf papers ls – view daily papers from the Hub.

Collaboration

Discussions and Pull Requests

Manage discussions and pull requests with hf discussions:

• hf discussions list – list discussions.
• hf discussions create – create a discussion.
• hf discussions info – get discussion information.
• hf discussions comment – add a comment.
• hf discussions close – close a discussion.
• hf discussions reopen – reopen a discussion.
• hf discussions rename – rename a discussion.
• hf discussions diff – view the diff of a pull request.
• hf discussions merge – finalize (merge) a pull request.

Collections

Organize Hub items into collections:

• hf collections add-item – add an item to a collection.
• hf collections update – update a collection.
• hf collections list – list collections.

Deployment and Infrastructure

Inference Endpoints

Deploy and manage Inference Endpoints:

• hf endpoints deploy – deploy an endpoint.
• hf endpoints pause – pause an endpoint.
• hf endpoints resume – resume an endpoint.
• hf endpoints scale-to-zero – scale an endpoint to zero.
• hf endpoints catalog – view the endpoint catalog.

Compute Jobs

Run compute jobs on Hugging Face infrastructure:

• hf jobs uv – run a Python script with inline dependencies.
• hf jobs stats – monitor resource usage for jobs.

Spaces

Manage Spaces:

• hf spaces dev-mode – enable or manage dev mode for a Space.
• hf spaces hot-reload – enable hot-reload (avoids full restarts on Python file changes).

Webhooks

Create and manage webhooks:

• hf webhooks create – create a new webhook.
• hf webhooks watch – watch webhook events.
• hf webhooks enable – enable an existing webhook.
• hf webhooks disable – disable a webhook.

Extensions and Skills

Extend the CLI:

• hf extensions install REPO_ID – install a CLI extension from a GitHub repository (using the repository ID).
• hf skills add – add an AI assistant skill.

Global Flags

Modify output behavior:

• --format json – output machine-readable JSON.
• -q or --quiet – limit output to IDs only.

Constraints and Caveats

• The hf command replaces the deprecated huggingface-cli.
• hf upload-large-folder is deprecated; always use hf upload.
• Authentication is recommended via HF_TOKEN or --token.
• Extensions are installed from GitHub repositories.
• Cache prune removes only detached revisions; cache verify performs checksum checks.
• Webhooks enable/disable toggle existing webhooks.
• Spaces dev-mode and hot-reload affect Python file behavior.
• SQL queries use DuckDB internally against dataset parquet URLs.
• Jobs uv runs Python scripts with inline dependencies; stats monitors resources.
• Endpoints scale-to-zero is a specific operation.
• Discussions diff shows PR changes; merge finalizes pull requests.
• Repos duplicate clones to a new ID; move transfers between namespaces.
• Upload is recommended for single-commit and handles resumable uploads for large directories.
• Sync syncs between local directory and a bucket.

Failure Modes

• Authentication failure: Missing or invalid HF_TOKEN or --token.
• Upload failure: Network interruption (resumable for large directories, but may fail for small files).
• Download failure: REPO_ID does not exist or access is denied.
• Repository operations failure: Invalid namespace or insufficient permissions.
• SQL query failure: Inaccessible parquet URLs or invalid query syntax.
• Cache verify failure: Checksum mismatch.
• Webhook creation failure: Invalid endpoint or insufficient permissions.
• Extension installation failure: Invalid or incompatible GitHub repository.
• Space operations failure: Improper Space configuration.
• Endpoint deployment failure: Quota exceeded or invalid configuration.
• Job execution failure: Script or dependency errors.
• Bucket operations failure: Non-existent bucket or insufficient permissions.
• Collection operations failure: Item already exists or insufficient permissions.
• Discussion/PR operations failure: Not authorized or state conflict.
• Deprecated command usage: Using upload-large-folder may produce warnings or errors.