Hugging Face CLI commands

Command lines for hf, the CLI that ships with the huggingface_hub Python package, checked against the CLI guide and the generated CLI reference of release 2.1.1: installing, logging in, downloads, uploads, repositories, Spaces, buckets, the local cache, Jobs, Inference Endpoints, webhooks and environment variables. The older huggingface-cli command has been removed, so hf auth login and hf cache ls replace its login and scan-cache forms. Experimental sandbox commands are left out. Example names such as gpt2 come from the documentation.

396 commands in 25 sections. Checked row by row against Hugging Face Hub docs: Command Line Interface (CLI) guide, huggingface_hub 2.1.1 on . Edited by Jay.

Installing and updating 13

CommandWhat it does
curl -LsSf https://hf.co/cli/install.sh | bashInstall on macOS or LinuxStandalone installer, the method the guide recommends; it also installs the hf-cli skill for AI agents.
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"Install on WindowsRuns the same standalone installer from PowerShell.
curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skillInstall without the agent skillSkips the global hf-cli skill that the installer otherwise adds for Claude Code and similar agents.
pip install -U "huggingface_hub"Install or upgrade with pipThe hf command ships inside the core Python package, so no extra is needed.
brew install hfInstall with Homebrew
uvx hf auth loginRun a command without installinguvx runs the latest release in an isolated environment each time, with nothing installed permanently.
hf updateUpdate the CLIDetects whether hf came from Homebrew, the standalone installer or pip and runs the matching upgrade.
hf --helpList commands and global optionsThe same flag after any command, such as hf upload, prints the options of that command.
hf upload --helpShow one command's options
hf versionPrint the CLI version
hf envPrint environment detailsOutput lists library version, platform, token path and cache settings, ready to paste into a GitHub issue.
hf --install-completionInstall shell completionSets up tab completion for the shell you are running.
hf --show-completionPrint the completion scriptPrints the script without installing it, so it can be copied or customised.

Agent skills and extensions 10

CommandWhat it does
hf skills addInstall the hf-cli agent skillAdds the skill to the current project so coding agents that read .agents/skills learn the hf commands.
hf skills add --globalInstall the skill for all projectsInstalls at user level rather than inside the project directory.
hf skills add huggingface-gradio --dest=~/my-skillsInstall a named skill elsewhereTakes a marketplace skill name and writes it into a skills directory of your choice.
hf skills listList marketplace skills
hf skills updateUpdate installed skillsRefreshes the marketplace skills installed in the project; add a name to update just one.
hf extensions install hf-claudeInstall a CLI extensionExtensions are public GitHub repositories named hf-NAME, optionally prefixed with their owner.
hf extensions listList installed extensions
hf extensions searchSearch available extensionsLooks on GitHub for repositories tagged with the hf-extension topic.
hf extensions updateUpdate all extensionsGive an extension name to bring only that one to its latest version.
hf extensions remove claudeRemove an extension

Logging in and tokens 13

Older tutorials write these commands as huggingface-cli login, whoami and logout. That command has been removed; hf, introduced in v0.34, replaces it.

CommandWhat it does
hf auth loginLog in to the HubStarts a browser login by default: it prints a URL and a short code, then saves a self-refreshing token.
hf auth login --forceLog in againWithout this flag an existing login skips the prompt; use it to switch tokens.
hf auth login --token $HF_TOKENLog in with a tokenNon-interactive form for scripts; the token comes from an environment variable, not from the command history.
hf auth login --token $HF_TOKEN --add-to-git-credentialLog in and add git credentialAlso saves the token in the configured git credential helper, which matters only when you run git yourself.
hf auth login --format agentLog in from an AI agentNever prompts: it runs the browser flow and prints instructions the agent passes on to its user.
hf auth whoamiShow the logged-in accountPrints your username and the organizations you belong to, or an error when not logged in.
hf auth whoami --format jsonShow the account as JSON
hf auth logoutLog outDeletes all tokens stored on the machine; a login that comes from the HF_TOKEN variable is not affected.
hf auth logout --token-name my-tokenRemove one stored token
hf auth listList stored tokensShows every access token saved on the machine; ls works as an alias.
hf auth switchSwitch between stored tokensMakes another saved access token the active one.
hf auth switch --token-name my-tokenSwitch to a named token
hf auth tokenPrint the current tokenWrites the active access token to stdout, so it can be piped into another command.

Downloading files and repositories 20

CommandWhat it does
hf download REPO_IDDownload a repositoryWith only a repo ID, every file of the model repo goes into the cache and the snapshot path is printed.
hf download gpt2 config.jsonDownload a single fileThe last line of output is always the local path of the file.
hf download gpt2 config.json model.safetensorsDownload several named files
hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensorsDownload a file from a subfolderWrite the path inside the repo in POSIX form, with forward slashes.
hf download meta-llama/Llama-3.2-1B-Instruct --include "*.safetensors" --exclude "*.bin"Download files by patternGlob patterns pick the files: --include keeps matches, --exclude drops them.
hf download HuggingFaceH4/ultrachat_200k --repo-type datasetDownload a datasetWithout --repo-type the ID is read as a model repo.
hf download HuggingFaceH4/zephyr-chat --repo-type spaceDownload a Space
hf download bigcode/the-stack --repo-type dataset --revision v1.1Download a specific revision--revision takes a commit hash, branch name or tag; the default is the latest commit on main.
hf download hf://datasets/bigcode/[email protected]Download with an hf:// URIThe URI already carries repo type and revision, so --repo-type and --revision raise an error next to it.
hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquetDownload one file from a pull request
hf download hf://datasets/HuggingFaceM4/FineVision/art/Download a subfolderThe trailing slash marks the path as a folder.
hf download hf://openai-community/gpt2/config.jsonDownload with a bare model URIA URI with no type prefix points at a model repo.
hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyuDownload a file into a folderThe file lands in that folder, not the cache; a .cache/huggingface subfolder there tracks what is up to date.
hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./models/llamaDownload a repo into a folder
hf download openai-community/gpt2 --dry-runPreview a downloadLists every file with the bytes still to fetch and downloads nothing.
hf download adept/fuyu-8b --cache-dir ./path/to/cacheUse another cache directoryOverrides the default cache location, which comes from HF_HOME.
hf download gpt2 config.json --token=hf_****Pass a token explicitlyFor private or gated repos when the token saved by the login should not be used.
hf download gpt2 --quietDownload quietlyOnly the final path is printed, which suits passing the result to another command in a script.
hf download REPO_ID --force-downloadDownload again despite the cacheFetches the files even when cached copies exist.
hf download REPO_ID --max-workers INTEGERSet parallel download workersEight workers run in parallel unless another number is given.

Uploading files and folders 19

CommandWhat it does
hf upload REPO_ID LOCAL_PATH PATH_IN_REPOUpload a file or folderLOCAL_PATH defaults to the current directory, and a repo that does not exist yet is created.
hf upload my-cool-model . .Upload the current directorySends the working directory to the root of the repo.
hf upload my-cool-model ./models .Upload one folder
hf upload my-cool-model ./path/to/curated/data /data/trainUpload to a path in the repoThe third argument is the destination folder inside the repository.
hf upload Wauplin/my-cool-model ./models/model.safetensorsUpload a single fileWith no third argument the file keeps its local name in the repo.
hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensorsUpload a file to a repo folder
hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"Mirror a local folder to a SpaceUploads everything except the logs folder and deletes remote files that are gone locally.
hf upload Wauplin/my-cool-dataset ./data /train --repo-type=datasetUpload to a dataset
hf upload MyCoolOrganization/my-cool-model . .Upload to an organizationThe organization has to be written in the repo ID; otherwise the repo is a personal one.
hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104Upload to a branch or pull requestTargets a revision other than main; a missing branch is created from main unless --create-pr is set.
hf upload bigcode/the-stack . . --repo-type dataset --create-prUpload as a new pull requestFor repos you cannot push to: the files go into a pull request for the owners to review.
hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csvUpload with an hf:// URIRepo type, revision and path in the repo are all read from the URI.
hf upload hf://Wauplin/my-cool-model ./modelsUpload a folder to a URI
hf upload training-model logs/ --every=10Upload at regular intervalsCommits the folder again every 10 minutes, for example training logs.
hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%"Set the commit messageReplaces the default commit title and description.
hf upload Wauplin/my-cool-model ./models . --token=hf_****Upload with an explicit tokenOtherwise the token saved by hf auth login is used.
hf upload Wauplin/my-cool-model ./models . --quietUpload quietlyPrints only the URL of the uploaded files.
hf upload REPO_ID --privateCreate the repo as privateApplies only when the upload creates the repo; an existing repo keeps its visibility.
hf upload HuggingFaceM4/Docmatix --repo-type=dataset /path/to/local/docmatixUpload a very large folderFiles are streamed in several commits; rerunning the same command after an interruption skips what is already uploaded.

Working through git 4

CommandWhat it does
git clone [email protected]:bigscience/bloomClone a model repository with gitSSH form from the Hub docs; add your public key in the account settings to reach private repos or push.
git xet installSet up git-xetRun once before cloning, because repositories on the Hub are Xet-backed.
git lfs installSet up Git LFS
hf lfs-enable-largefiles PATHEnable large files in a cloneSets up git-lfs in the local repository at PATH to push large files in chunks through a multipart transfer agent.

Creating and managing repositories 22

CommandWhat it does
hf repos create REPO_IDCreate a repositoryMakes a model repo unless --repo-type says dataset or space.
hf repos create my-cool-dataset --repo-type dataset --privateCreate a private dataset
hf repos create my-gradio-space --repo-type space --sdk gradioCreate a Gradio SpaceThe reference marks --sdk as required whenever the type is space.
hf repos create my-jupyterlab --type space --template SpacesExamples/jupyterlabCreate a Space from a templateTakes a template repo ID or its short name; hf spaces templates lists them.
hf repos create my-model --region usCreate a repo in a cloud regionAccepts us or eu and needs a Team plan or above.
hf repos create REPO_ID --exist-okCreate only if missingStops the command from failing when the repo is already there.
hf repos lsList your repositoriesCovers models, datasets, Spaces and buckets with storage use, largest first; only the first 30 are shown.
hf repos ls --type modelList one repository type--type also accepts dataset, space and bucket.
hf repos ls --search "bert"Search your repositories by name
hf repos ls --namespace my-orgList an organization's repositories
hf repos ls --limit 0List repositories without a limit
hf repos ls -qPrint repository IDs only
hf repos ls --limit 0 --format json | jq '.[].id'Export all repository IDsJSON output piped through jq; --limit 0 makes the export cover every repo.
hf repos duplicate openai/gdpval --type datasetDuplicate a repositoryCopies it on the server into your namespace and keeps the git history.
hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --privateDuplicate into an organizationThe second ID names the copy; --private hides it.
hf repos delete Wauplin/my-cool-modelDelete a repositoryCannot be undone; -y answers the confirmation prompt in advance.
hf repos delete my-cool-dataset --repo-type datasetDelete a dataset repository
hf repos move old-namespace/my-model new-namespace/my-modelMove a repo to another namespace
hf repos settings Wauplin/my-cool-model --gated autoGate access to a repository--gated takes auto, manual or false.
hf repos settings my-model --privateMake a repository private
hf repos settings REPO_ID --publicMake a repository public
hf repos settings my-space --repo-type space --protectedProtect a SpaceThe protected setting exists for Spaces only.

Repository files, branches and tags 17

hf cp, hf repos cp and hf buckets cp are one and the same command.

CommandWhat it does
hf repos delete-files Wauplin/my-cool-model folder/Delete a folder from a repo
hf repos delete-files Wauplin/my-cool-model file.txt folder/pytorch_model.binDelete several files
hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin"Delete files by patternPatterns follow fnmatch, where * also matches across folder boundaries.
hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txtDelete a file with an explicit token
hf repos branch create Wauplin/my-cool-model devCreate a branch
hf repos branch create Wauplin/my-cool-model release-1 --revision refs/pr/104Branch off a given revision
hf repos branch delete Wauplin/my-cool-model devDelete a branch
hf repos tag create my-model v1.0Tag a repository
hf repos tag create my-model v1.0 -m "First release"Tag with a description
hf repos tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104Tag a specific revisionWithout --revision the tag points at the main branch.
hf repos tag create bigcode/the-stack v1.0 --repo-type datasetTag a dataset
hf repos tag list my-modelList tagsThe subcommand can also be written ls.
hf repos tag delete my-model v1.0Delete a tagAsks before deleting; -y skips that step.
hf cp ./model.safetensors hf://username/my-model/model.safetensorsCopy a local file to a repohf cp moves one file at a time when a local path is involved; use hf upload for whole folders.
hf cp hf://datasets/username/my-dataset@refs/pr/1/data.csv ./data.csvCopy a repo file to disk
hf cp hf://username/source-model/config.json hf://username/dest-model/config.jsonCopy a file between reposHub-to-Hub copies work only inside one storage region.
hf cp hf://buckets/username/my-bucket/config.json - | jq .Print a remote file to stdoutA dash as destination means stdout; as source it means stdin.

Finding models 20

CommandWhat it does
hf models lsList trending models
hf models ls --search "lora"Search models
hf models ls --author QwenList models by author
hf models ls --pipeline-tag summarizationList models for a task
hf models ls --num-parameters min:6B,max:128BFilter models by parameter count
hf models ls --no-gated --author googleList only non-gated models--gated shows the opposite set, models that need an access request.
hf models ls --apps llama.cppList models an app can run
hf models ls --sort downloads --limit 10List the most downloaded modelsSort keys are created_at, downloads, last_modified, likes and trending_score.
hf models ls --inference-provider fireworks-ai --sort downloadsList models served by a provider
hf models ls --warm --search llamaList models that are served now--warm keeps models that at least one inference provider is currently serving.
hf models ls meta-llama/Llama-3.2-1B-InstructList a model repo's filesWith a repo ID the command lists files; with none it lists models.
hf models ls meta-llama/Llama-3.2-1B-Instruct -RList model files recursively
hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -hShow model files as a treeTree layout with sizes in human-readable units.
hf models ls meta-llama/Llama-3.2-1B-Instruct --revision mainList files at a revision
hf models info Lightricks/LTX-2Show model details
hf models info Qwen/Qwen3.5-9B --expand downloads,likes,tagsShow selected model propertiesReturns only the listed properties plus the ID.
hf models card google/gemma-4-31B-itPrint a model cardPrints the README: the YAML metadata followed by the text.
hf models card google/gemma-4-31B-it --metadataPrint model card metadata
hf models card google/gemma-4-31B-it --metadata --format jsonPrint card metadata as JSON
hf models card google/gemma-4-31B-it --textPrint model card text onlyThe YAML frontmatter at the top is left out.

Finding datasets 16

CommandWhat it does
hf datasets lsList trending datasets
hf datasets ls --search "code"Search datasets
hf datasets ls --filter benchmark:officialList official benchmark datasetsThese are the datasets that have a leaderboard.
hf datasets ls --sort downloads --limit 10List the most downloaded datasets
hf datasets ls HuggingFaceFW/finewebList a dataset repo's files
hf datasets ls HuggingFaceFW/fineweb -R -hList dataset files with sizes
hf datasets ls HuggingFaceFW/fineweb --treeShow dataset files as a tree
hf datasets info HuggingFaceFW/finewebShow dataset details
hf datasets card HuggingFaceFW/finewebPrint a dataset card
hf datasets card HuggingFaceFW/fineweb --metadata --format jsonPrint dataset metadata as JSON
hf datasets leaderboard SWE-bench/SWE-bench_VerifiedShow a benchmark leaderboardLists model scores for the benchmark, 20 results unless --limit says otherwise.
hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format jsonExport top leaderboard entries
hf datasets parquet cfahlgren1/hub-statsList parquet file URLs of a datasetEligible datasets are converted to Parquet by the Dataset Viewer; the table shows subset, split and URL.
hf datasets parquet cfahlgren1/hub-stats --subset modelsList parquet URLs of one subset
hf datasets parquet cfahlgren1/hub-stats --split trainList parquet URLs of one split
hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')"Query dataset parquet with SQLRuns the query with DuckDB, which has to be installed as a Python package or as its own CLI.

Finding Spaces and papers 17

CommandWhat it does
hf spaces lsList trending Spaces
hf spaces ls --search "3d"Search Spaces
hf spaces ls --sort likes --limit 10List the most liked Spaces
hf spaces ls victor/deepsiteList a Space repo's files
hf spaces info victor/deepsiteShow Space details
hf spaces card mteb/leaderboardPrint a Space card
hf spaces search "generate image"Search Spaces semanticallySemantic search over Spaces; returns 10 running Spaces unless told otherwise.
hf spaces search "identify objects in pictures" --sdk gradio --limit 5Search Spaces of one SDK
hf spaces search "remove background from photo" --description --jsonSearch with descriptions as JSON--description adds the AI-generated summary of each Space.
hf papers lsList daily papers
hf papers ls --sort=trendingList trending papers
hf papers ls --date=todayList today's papers--date also takes an ISO date such as 2025-01-23.
hf papers ls --week=2025-W09List papers of a week
hf papers ls --submitter=akhaliqList papers by submitter
hf papers search "vision language"Search papers
hf papers info 2601.15621Show paper detailsReturns the structured metadata of the paper as JSON.
hf papers read 2601.15621Read a paper as Markdown

Collections 8

CommandWhat it does
hf collections lsList collections
hf collections ls --owner nvidiaList collections of an owner
hf collections info username/my-collection-slugShow a collection
hf collections create "My Models"Create a collection
hf collections create "My Models" --description "A collection of my favorite models" --privateCreate a private collectionThe description is limited to 150 characters.
hf collections add-item username/my-collection moonshotai/kimi-k2 modelAdd an item to a collectionThe last argument is the item type: model, dataset, space, paper, collection or bucket.
hf collections update username/my-collection --title "New Title"Rename a collection
hf collections delete username/my-collectionDelete a collection

Running and debugging Spaces 23

CommandWhat it does
hf spaces pause username/my-spacePause a SpacePaused time is not billed; the container is torn down, so files on its ephemeral disk are lost.
hf spaces restart username/my-spaceRestart a SpaceAlso the way to bring a paused Space back.
hf spaces restart username/my-space --factory-rebootRebuild a Space from scratchRebuilds the image and ignores the build cache.
hf spaces wait username/my-spaceWait until a Space is upBlocks until building and starting are over; exit code 0 means RUNNING, anything else a failure such as BUILD_ERROR.
hf spaces wait username/my-space --timeout 5mWait with a time limitThe limit is a number with s, m, h or d; plain numbers are seconds.
hf spaces restart username/my-space && hf spaces wait username/my-spaceRestart and wait in one line
hf spaces logs username/my-spacePrint the run logs of a Space
hf spaces logs username/my-space --buildPrint the build logsUse it for a Space stuck in BUILD_ERROR; the default is the run log.
hf spaces logs -f username/my-spaceFollow Space logsKeeps printing until the server closes the stream.
hf spaces logs -n 50 username/my-spaceShow the last 50 log lines
hf spaces hardwareList Space hardware optionsThe table includes pricing for each flavor.
hf spaces settings username/my-space --hardware t4-mediumChange Space hardware
hf spaces settings username/my-space --sleep-time 3600Set the sleep timeoutIdle seconds before the Space sleeps, -1 for never; only on upgraded hardware.
hf spaces zero-gpu quotaCheck the ZeroGPU quotaShows how much GPU time is left and when the quota resets.
hf spaces dev-mode my-user-name/deepsiteEnable Dev Mode
hf spaces dev-mode SPACE_ID --stopDisable Dev Mode
hf spaces ssh username/my-spaceOpen an SSH session in a SpaceConnects to the Dev Mode container, prompting to enable Dev Mode if it is off; your SSH public key must be registered.
hf spaces ssh username/my-space --dry-runPrint the SSH command for a Space
hf spaces ssh username/my-space --autoSSH and enable Dev Mode unasked
hf spaces ssh username/my-space -i ~/.ssh/id_ed25519SSH with a chosen identity file
hf spaces hot-reload username/repo-name app.pyEdit a Space file liveOpens an interactive editor on the remote Python file and reloads it with no rebuild or restart.
hf spaces hot-reload username/repo-name -f app.pyHot-reload from a local filePatches the remote app.py with the local copy.
hf spaces templatesList Space templatesA template from this list can be given to hf repos create with --template.

Space secrets, variables and volumes 12

CommandWhat it does
hf spaces secrets ls username/my-spaceList Space secretsShows keys, descriptions and update times; secret values are write-only and never printed.
hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...Add or update a secretA key that already exists is overwritten.
hf spaces secrets add username/my-space -s HF_TOKENAdd a secret from your environmentA name with no value is read from the local environment, which keeps it out of the shell history.
hf spaces secrets add username/my-space --secrets-file .env.secretsLoad secrets from a file
hf spaces secrets delete username/my-space OPENAI_API_KEY --yesDelete a secret
hf spaces variables ls username/my-spaceList Space variablesVariables are not secret, so the list shows values as well as keys.
hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512Add environment variables
hf spaces variables add username/my-space --env-file .envLoad variables from a file
hf spaces variables delete username/my-space MAX_TOKENS --yesDelete a variable
hf spaces volumes set username/my-space -v hf://models/username/my-model:/modelsMount a volume in a SpaceReplaces the current set of volumes; data on a mounted volume or bucket survives restarts.
hf spaces volumes ls username/my-spaceList Space volumes
hf spaces volumes delete username/my-spaceRemove all Space volumes

Discussions and pull requests 18

CommandWhat it does
hf discussions list username/my-modelList open discussions and PRsOnly open items are listed unless --status says otherwise.
hf discussions list username/my-model --kind pull_request --status mergedList merged pull requestsKinds are discussion, pull_request or all; statuses are open, closed, merged, draft or all.
hf discussions list username/my-model --author aliceList discussions by author
hf discussions ls username/my-model --quietPrint discussion numbers only
hf discussions info username/my-model 5Show a discussion or PRPrints title, status and author plus every event of the conversation.
hf discussions diff username/my-model 5Show the diff of a pull request
hf discussions create username/my-model --title "Bug report"Open a discussion
hf discussions create username/my-model --title "Feature request" --body "Please add X"Open a discussion with a description
hf discussions create username/my-model --title "Report" --body-file report.mdOpen a discussion from a file
hf discussions create username/my-model --title "Fix typo" --pull-requestOpen a pull requestThe flag can be shortened to --pr.
hf discussions comment username/my-model 5 --body "Thanks for reporting!"Comment on a discussion
hf discussions comment username/my-model 5 --body-file review.mdComment from a fileA dash as the file name reads the text from stdin.
hf discussions edit username/my-model 5 abc123 --body "Updated comment."Edit a commentThe comment ID comes from hf discussions info.
hf discussions close username/my-model 5Close a discussion or PRAsks for confirmation unless --yes is given.
hf discussions close username/my-model 5 --yes --comment "Resolved"Close with a comment, no prompt
hf discussions reopen username/my-model 5 --yesReopen a discussion
hf discussions merge username/my-model 5 --yesMerge a pull request
hf discussions rename username/my-model 5 "Updated title"Rename a discussion

Buckets 22

CommandWhat it does
hf buckets create my-bucketCreate a bucketCreated under your own namespace; buckets are mutable object storage with no git history.
hf buckets create my-bucket --privateCreate a private bucket
hf buckets listList your bucketshf buckets ls is the shorthand for the same listing.
hf buckets ls my-orgList an organization's buckets
hf buckets list --search "checkpoint"Filter buckets by name
hf buckets info username/my-bucketShow bucket detailsThe details come back as JSON.
hf buckets settings username/my-bucket --privateMake a bucket private
hf buckets settings username/my-bucket --publicMake a bucket public
hf buckets move user/old-bucket user/new-bucketRename or move a bucket
hf buckets delete username/my-bucket --yesDelete a bucketWithout --yes the command asks for confirmation first.
hf buckets list username/my-bucketList files in a bucket
hf buckets list username/my-bucket -R -hList bucket files recursively-h prints file sizes in readable units and shortens dates.
hf buckets list username/my-bucket --tree -h -RShow a bucket as a tree
hf buckets list username/my-bucket/sub -RList files under a prefix
hf buckets rm username/my-bucket/old-model.binRemove a file from a bucket
hf buckets rm username/my-bucket/logs/ --recursiveRemove everything under a prefix
hf buckets rm username/my-bucket --recursive --include "*.tmp"Remove bucket files by pattern--include and --exclude work only together with --recursive.
hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-runPreview a bucket removal
hf cp ./data.csv hf://buckets/username/my-bucket/logs/Copy a local file into a bucketA destination ending in a slash keeps the local file name.
hf cp hf://buckets/username/my-bucket/config.jsonCopy a bucket file to this folderWith the destination left out, the file is written to the current directory.
hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/Copy a repo folder to a bucketThe reverse direction, bucket to repo, is not supported yet.
hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/Copy between bucketsA trailing slash on the source copies only the folder contents, rsync-style.

Syncing folders with a bucket 10

CommandWhat it does
hf buckets sync ./data hf://buckets/username/my-bucketSync a folder up to a bucketCompares both sides and transfers only the files that changed.
hf buckets sync hf://buckets/username/my-bucket ./dataSync a bucket down to a folder
hf buckets sync ./data hf://buckets/username/my-bucket --deleteSync and delete extra filesRemoves files at the destination that the source no longer has.
hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"Sync only matching files
hf buckets sync ./data hf://buckets/username/my-bucket --existingSync without creating new filesUpdates files already at the destination and adds nothing new.
hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existingSync only new filesCreates missing files and leaves those already at the destination untouched.
hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonlSave a sync planWrites the planned operations to a JSONL file for review and transfers nothing.
hf buckets sync --apply sync-plan.jsonlApply a saved sync plan
hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .Print the sync plan as JSONL
hf sync SOURCE DESTSync with the short aliasTop-level alias of hf buckets sync with the same options.

Cache management 21

hf cache scan and hf cache delete were removed in v1.0. hf cache ls, hf cache rm and hf cache prune are the replacements.

CommandWhat it does
hf cache lsList cached repositoriesOne line per repository with its size on disk; the summary gives totals for repos and revisions.
hf cache ls --revisionsList cached revisionsBreaks each repository down into its snapshots.
hf cache ls --filter "size>30g" --revisionsFind large cached revisions
hf cache ls --filter "size>1GB" --limit 20List large cache entriesFilters also accept forms such as type=model and accessed>7d, and can be repeated.
hf cache ls --format jsonList the cache as JSON
hf cache list --sort size:descSort the cache listingKeys are accessed, modified, name and size, each with :asc or :desc; ls is the alias of list.
hf cache rm model/gpt2Delete a cached repositoryShows what will go and asks for confirmation; the target is the repo ID with its type in front.
hf cache rm model/gpt2 --dry-runPreview a cache deletion
hf cache rm model/gpt2 --yesDelete from the cache without asking
hf cache rm hf://models/openai-community/gpt2Delete a cached repo by URI
hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-runDelete one cached fileThe file is removed from every cached revision; folders and glob patterns are not accepted.
hf cache rm model/t5-small 8f3ad1c --dry-runDelete a repo and a revision togetherRepositories and revision hashes can be mixed in one call.
hf cache rm $(hf cache ls --filter "accessed>1y" -q) -yDelete entries unused for a yearThe inner listing prints only IDs, which become the deletion targets.
hf cache pruneRemove unreferenced revisionsAlso clears .incomplete files from interrupted downloads and shared blobs that nothing references.
hf cache prune --dry-runPreview a cache prune
hf cache verify gpt2Verify cached file checksumsCompares local files with the checksums on the Hub and exits non-zero on a mismatch.
hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5Verify a specific revision
hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type datasetVerify a cached dataset
hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repoVerify a folder outside the cache
hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-filesFail on missing or extra filesBy default such files only produce warnings.
hf cache verify me/private-model --token hf_***Verify a private repo

Running Jobs 23

CommandWhat it does
hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")'Run a command in a Docker imageStarts the Job on Hugging Face infrastructure and shows its logs until it ends.
hf jobs run --detach python:3.12 python script.pyRun a Job in the backgroundReturns at once and prints only the Job ID.
hf jobs run --flavor cpu-basic python:3.12 -- python --helpSeparate Job options from the commandEverything after the double dash belongs to your command; Jobs leaves it uninterpreted.
hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'Run under an organization
hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'Run a Job from a SpaceThe image argument here is a Space, not a Docker Hub image.
hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.pySet a Job timeoutJobs stop after 30 minutes by default; the value takes an s, m, h or d suffix.
hf jobs run -e FOO=foo python:3.12 python script.pyPass an environment variableRepeat -e for more variables, or load a whole file with --env-file.
hf jobs run --secrets HF_TOKEN python:3.12 python script.pyPass your Hub token as a secretA secret named without a value is read from your environment; secrets are encrypted on the server.
hf jobs run -v hf://org/my-model:/data -v hf://buckets/org/b:/mnt python:3.12 python script.pyMount repos and buckets as volumesModels, datasets and Spaces mount read-only; buckets are read-write unless :ro is appended.
hf jobs run --attempts 3 --detach python:3.12 python train.pyRetry a failing JobThe count includes the first run, so 3 allows up to two retries.
hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000Expose a port without a tokenPlain --expose keeps the port behind token authentication; both flags can be repeated.
hf jobs run --ssh --detach python:3.12 sleep infinityStart a Job reachable over SSHAccess is limited to users with write access to the namespace who have an SSH key registered.
hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"Label a JobLabels are key=value metadata; a key given alone gets an empty value.
hf jobs run --name training-v2 python:3.12 python train.pyName a JobNames need not be unique; without one a name is derived from the image or script.
hf jobs run python:3.12 python train.py && echo "training succeeded"Chain a command after a JobA non-detached run exits non-zero when the Job fails, so the second command is skipped.
hf jobs uv run my_script.pyRun a UV scriptUV scripts are Python files that declare their dependencies inline; the guide marks the feature experimental.
hf jobs uv run --flavor t4-small ml_training.pyRun a UV script on a GPU
hf jobs uv run --with transformers --with torch train.pyAdd packages to a UV run
hf jobs uv run process.py input.csv output.parquetPass arguments to a UV script
hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.pyRun a UV script from a URL
hf jobs uv run -v ./my-data:/data process.pyMount a local folder in a JobThe folder is first synced to your jobs-artifacts bucket and mounted read-only unless :rw is added.
hf jobs uv run --dry-run script.pyPreview a UV JobShows the configuration that would be sent and submits nothing.
hf jobs hardwareList Job hardware flavors

Monitoring Jobs 21

CommandWhat it does
hf jobs lsList running JobsShows running and scheduling Jobs only, 100 at most.
hf jobs ls -aList all JobsLifts the default restriction to running and scheduling Jobs.
hf jobs ls --status running,schedulingFilter Jobs by status
hf jobs ls -a --label model=Qwen3-06BFilter Jobs by label
hf jobs ls -a --name training-v2Filter Jobs by name--name is shorthand for --label name=NAME.
hf jobs ps -a --limit 0List every Job without a capps is another spelling of ls; --limit 0 removes the cap of 100.
hf jobs inspect JOB_IDShow Job detailsTakes one Job ID or several at once.
hf jobs logs JOB_IDPrint Job logsPrints what is available so far and returns.
hf jobs logs -f JOB_IDFollow Job logsKeeps streaming until the Job completes.
hf jobs logs --tail 20 JOB_IDShow the last log linesCombined with -f, streaming starts from those last lines.
hf jobs statsShow resource usage of running Jobs
hf jobs stats JOB_IDShow resource usage of one Job
hf jobs cancel JOB_IDCancel a Job
hf jobs wait JOB_IDWait for a Job to finishBlocks until the Job reaches a terminal state and exits non-zero if it failed.
hf jobs ls -q | xargs hf jobs waitWait for all running Jobs
hf jobs rerun JOB_IDRun a Job againStarts a new Job from the saved spec, attempt count included, and streams its logs.
hf jobs labels JOB_ID --name training-v2Rename a JobPassing --name alone keeps the other labels, whereas --label replaces them all.
hf jobs expose JOB_ID 8000 --public 9000Change exposed portsApplies without rerunning the Job; ports left out of the new list are closed.
hf jobs expose JOB_ID --clearClose all exposed ports
hf jobs ssh JOB_IDSSH into a running JobWorks for Jobs that were started with the --ssh flag.
hf jobs ssh JOB_ID --dry-runPrint the SSH command for a Job

Scheduled Jobs 13

CommandWhat it does
hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'Schedule a recurring JobThe schedule is @hourly, @daily, @weekly, @monthly, @yearly, @annually or a CRON expression.
hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'Schedule with a CRON expression
hf jobs scheduled uv run @hourly --name hourly-script my_script.pySchedule a UV script
hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.pySchedule a Job with a timeout
hf jobs scheduled lsList active scheduled Jobs
hf jobs scheduled ls --allList all scheduled Jobs
hf jobs scheduled ls --status suspendedList suspended scheduled Jobs
hf jobs scheduled inspect SCHEDULED_JOB_IDShow a scheduled Job
hf jobs scheduled suspend SCHEDULED_JOB_IDPause a scheduled Job
hf jobs scheduled resume SCHEDULED_JOB_IDResume a scheduled Job
hf jobs scheduled reschedule SCHEDULED_JOB_ID "0 9 * * 1"Change the scheduleAffects future runs; the example expression means Mondays at 9:00.
hf jobs scheduled trigger SCHEDULED_JOB_IDRun a scheduled Job nowStarts one run immediately and leaves the schedule as it is.
hf jobs scheduled delete SCHEDULED_JOB_IDDelete a scheduled Job

Inference Endpoints 16

hf inference-endpoints is the legacy alias of hf endpoints and still works.

CommandWhat it does
hf endpoints lsList Inference EndpointsLists your own namespace; --namespace targets an organization.
hf endpoints hardwareList deployable hardwareEach row is a valid vendor, region, accelerator and instance combination with its hourly price and your quota.
hf endpoints hardware --vendor aws --region eu-west-1Filter hardware by cloud and regionThe filter flags are the ones deploy takes, so the values can be reused as they are.
hf endpoints catalog lsList catalog modelsOne row per recipe, which is a tested hardware and engine combination.
hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10Filter the catalog
hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-InstructDeploy a catalog modelUses the default recipe of that model.
hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamxDeploy a specific recipeRecipe IDs come from the catalog listing; --repo cannot be combined with --recipe.
hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpointDeploy a catalog model under a name
hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-iclDeploy an endpoint from a Hub repoThe reference also marks --vendor and --region as required; hf endpoints hardware lists valid values.
hf endpoints describe my-endpointShow endpoint status and metadata
hf endpoints update my-endpoint --min-replica 2Change the minimum replica count
hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2Retune a running endpointPass the sizes on their own; the current engine image is fetched and updated in place.
hf endpoints pause my-endpointPause an endpoint
hf endpoints resume my-endpointResume an endpoint
hf endpoints scale-to-zero my-endpointScale an endpoint to zero
hf endpoints delete my-endpoint --yesDelete an endpointDeletion is permanent; --yes skips the confirmation.

Webhooks 9

CommandWhat it does
hf webhooks lsList your webhooks
hf webhooks info wh-abc123Show webhook detailsFull details are printed as JSON.
hf webhooks create --url https://example.com/hook --watch model:bert-base-uncasedCreate a webhook for a URL--watch takes type:name with type model, dataset, space, bucket, org or user, and can be repeated.
hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repoWatch several items, repo events only--domain limits events to repo or discussions; without it both are sent.
hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-cCreate a webhook that runs a JobTriggers the Job in place of pinging a URL; --url and --job-id exclude each other.
hf webhooks update wh-abc123 --url https://new-url.com/hookChange a webhookOnly the options given are changed, but --watch replaces the whole watched list.
hf webhooks disable wh-abc123Disable a webhook
hf webhooks enable wh-abc123Enable a webhook
hf webhooks delete wh-abc123 --yesDelete a webhook

Output formats 7

CommandWhat it does
--jsonPrint structured JSONAccepted by most hf commands and equal to --format json; suited to piping into jq.
-qPrint IDs onlyOne ID per line, the form to pipe into another command; the long spelling is --quiet.
--format agentPrint tab-separated valuesUntruncated output for AI agents; the default auto mode picks it when an agent calls the CLI.
--format humanPrint coloured tablesThe format auto selects in an interactive terminal.
--no-truncateShow full values in tablesStops long values being shortened with dots, even if the table overflows the terminal.
hf models ls --search bert --limit 2 --json | jq '.[].id'Extract IDs from JSON output
hf collections ls --owner nvidia -qList matching IDs one per line

Environment variables 22

CommandWhat it does
HF_TOKENAuthenticate with a tokenWhen set, it wins over any token saved by a login.
HF_HOMEMove the Hugging Face data folderHolds the token and the cache; defaults to ~/.cache/huggingface unless XDG_CACHE_HOME is set.
HF_HUB_CACHEMove the repository cacheWhere downloaded models, datasets and Spaces are kept; defaults to $HF_HOME/hub.
HF_XET_CACHEMove the Xet cacheXet keeps its shard cache and its staging data for uploads here, $HF_HOME/xet by default.
HF_TOKEN_PATHChange where the token is storedThe default location is the file $HF_HOME/token.
HF_HUB_OFFLINE=1Work offline from the cacheNo HTTP calls reach the Hub: downloads resolve to cached files and fail when nothing is cached.
export HF_HUB_DOWNLOAD_TIMEOUT=30Raise the download timeoutCure for read timeouts on slow connections; the default wait is 10 seconds.
HF_HUB_ETAG_TIMEOUTSet the metadata request timeoutSeconds to wait for repo metadata before falling back to cached files, 10 by default.
HF_HUB_VERBOSITYSet the log levelAccepts the five standard levels from debug to critical; warning is the default.
HF_DEBUGTurn on debug loggingBesides DEBUG-level logs, every request is printed as an equivalent cURL command.
HF_HUB_DISABLE_PROGRESS_BARS=1Hide progress bars
HF_HUB_DISABLE_TELEMETRY=1Turn off telemetryStops usage data collection across the Hugging Face libraries; DO_NOT_TRACK has the same effect.
HF_HUB_DISABLE_UPDATE_CHECK=1Silence the update noticeSkips the PyPI check hf makes at startup, at most once a day, and the hint about the hf-cli skill.
HF_HUB_DISABLE_IMPLICIT_TOKEN=1Send the token only for writesBy default a logged-in user sends the token with every request, which also covers private and gated repos.
HF_HUB_DISABLE_SYMLINKS=1Keep symlinks out of the cacheFiles are copied into the snapshot folders, at the cost of duplicates; one use is a cache shared across operating systems.
HF_HUB_DISABLE_XETTurn off hf-xet transfershf-xet is otherwise used automatically whenever it is installed.
HF_XET_HIGH_PERFORMANCE=1 hf download ...Download with maximum throughputRaises concurrency and buffer sizes; the Hub docs advise it for high-bandwidth machines with at least 64 GB of RAM.
HF_HUB_ENABLE_HF_TRANSFEROld fast-transfer switchDeprecated: hf_transfer can no longer be used now that all transfers go through hf-xet.
NO_COLORTurn off coloured outputWhen set, the hf CLI prints no ANSI colour codes.
XDG_CACHE_HOMEFallback for the data folderRead only while HF_HOME is unset; the data folder then becomes $XDG_CACHE_HOME/huggingface.
HUGGING_FACE_HUB_TOKENDeprecated token variableStill works but no longer takes precedence over HF_TOKEN, which replaces it.
HUGGINGFACE_HUB_CACHEDeprecated cache variableStill works but HF_HUB_CACHE, its replacement, wins when both are set.

Notes

Authentication

hf auth login opens a browser login and saves a token on the machine; private and gated repositories need one, as do uploads. hf auth whoami confirms which account is active and hf auth logout removes the stored tokens. On a shared machine or in CI, the token can instead be passed per command with --token or set in HF_TOKEN, which is used in place of the stored token. hf env prints the versions and paths the library sees, which is what to paste into a bug report.

Downloading and uploading

hf download REPO_ID fetches a repository into the cache and prints the local path; hf download meta-llama/Llama-3.2-1B-Instruct --include "*.safetensors" --exclude "*.bin" restricts it to patterns, which saves time and space for a repo that ships its weights in several formats. hf upload REPO_ID LOCAL_PATH PATH_IN_REPO pushes a file or folder and creates the repo when it does not exist yet; hf repos create REPO_ID makes one explicitly. The git route is git clone [email protected]:bigscience/bloom after git xet install, and hf lfs-enable-largefiles PATH prepares a clone for files over 5 GB.

The cache

Everything downloads into ~/.cache/huggingface/hub (or under HF_HOME), and models of tens of gigabytes accumulate there. hf cache ls reports what is cached with sizes per repository, and hf cache ls --revisions breaks that down per revision. hf cache rm model/gpt2 deletes a repository after a confirmation prompt and hf cache prune clears revisions that no branch or tag points to — the pair to run when a workstation runs out of space. The interactive selector of the old delete-cache command no longer exists. hf version prints the CLI version.

Questions

Is huggingface-cli still available?

No. The huggingface_hub migration guide says the deprecated huggingface-cli has been removed and that hf, introduced in v0.34, replaces it. The commands are grouped by resource, so the old login, whoami and logout became hf auth login, hf auth whoami and hf auth logout.

What replaced scan-cache and delete-cache?

hf cache ls lists what is cached, hf cache rm model/gpt2 deletes a repository, a revision or a single file, and hf cache prune removes revisions that nothing references. The intermediate hf cache scan and hf cache delete commands were removed in v1.0 as well.

Where does hf download put the files?

In the cache, by default ~/.cache/huggingface/hub, and it prints the resulting path on the last line. hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./models/llama writes to a folder of your choice instead, and the HF_HOME or HF_HUB_CACHE variables move the cache itself.

How do I log in on a server or in CI without a prompt?

Set the HF_TOKEN environment variable, which is used in place of any stored token, or run hf auth login --token $HF_TOKEN. The guide recommends an environment variable so the token does not end up in the command history.

Is there still a separate command for uploading very large folders?

The 2.1.1 reference lists none. The upload guide names hf upload REPO_ID LOCAL_PATH PATH_IN_REPO as the way to send very large folders too: files are streamed in several commits, and running the same command again after an interruption skips what was already uploaded.

Does HF_HUB_ENABLE_HF_TRANSFER still speed up transfers?

No. The variable is deprecated because all transfers now go through hf-xet and hf_transfer cannot be used any more. The documented replacement for maximum throughput is HF_XET_HIGH_PERFORMANCE=1.

Sources and checks

Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.

Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.