id       = "hf"
name     = "Hugging Face Hub CLI"
homepage = "https://huggingface.co/docs/huggingface_hub/guides/cli"
description = "The Hugging Face Hub CLI."
icon     = "SimpleIcons:huggingface"
executables   = ["hf"]

[dotfiles]

# https://huggingface.co/docs/huggingface_hub/guides/cli — `hf auth login`
# saves the active token at ~/.cache/huggingface/token and named tokens at
# ~/.cache/huggingface/stored_tokens by default. HF_HOME/HF_TOKEN_PATH can
# relocate these files, but those arbitrary environment paths cannot be named
# without inventing a root.
paths = []
secret = [
  "~/.cache/huggingface/token",
  "~/.cache/huggingface/stored_tokens",
]
side_effect = false

[commands]
format = 1
label = "Hugging Face Hub CLI"
description = "Download files or whole repositories from the Hub with hf download. Other hf commands and hf:// URIs are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["download"]
label = "Download from the Hub"
description = "Download a model, dataset or Space, or only some of its files, into the cache or a local folder."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://huggingface.co/docs/huggingface_hub/guides/cli"
revision = "2026-10-27"
evidence = """>>> hf download gpt2 config.json model.safetensors
>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
>>> hf download openai-community/gpt2 --dry-run
>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache"""

[[commands.subcommand.field]]
id = "repo_id"
label = "Repository ID"
description = "For example gpt2 or HuggingFaceH4/zephyr-7b-beta."
type = "string"
position = 0
sources = ["docs"]

[[commands.subcommand.field]]
id = "filenames"
label = "Files"
description = "Specific files in the repo; leave empty for the whole repository."
type = "string"
position = 1
multiple = true
min = 0
sources = ["docs"]

[[commands.subcommand.field]]
id = "repo_type"
label = "Repository type"
type = "string"
option = ["--repo-type"]
suggestions = [{ value = "model", label = "Model" }, { value = "dataset", label = "Dataset" }, { value = "space", label = "Space" }]
sources = ["docs"]

[[commands.subcommand.field]]
id = "revision"
label = "Revision"
description = "Commit hash, branch name or tag."
type = "string"
option = ["--revision"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "include"
label = "Include pattern"
type = "string"
option = ["--include"]
multiple = true
sources = ["docs"]

[[commands.subcommand.field]]
id = "exclude"
label = "Exclude pattern"
type = "string"
option = ["--exclude"]
multiple = true
sources = ["docs"]

[[commands.subcommand.field]]
id = "local_dir"
label = "Local folder"
type = "path"
option = ["--local-dir"]
path = { kind = "directory", role = "output" }
sources = ["docs"]

[[commands.subcommand.field]]
id = "cache_dir"
label = "Cache directory"
type = "path"
option = ["--cache-dir"]
path = { kind = "directory", role = "output" }
sources = ["docs"]

[[commands.subcommand.field]]
id = "dry_run"
label = "Dry run"
description = "List the files that would be downloaded without downloading."
type = "boolean"
option = ["--dry-run"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "repo"
label = "Download a repository"
fields = ["repo_id", "repo_type", "revision", "local_dir"]
required = ["repo_id"]

[[commands.subcommand.task]]
id = "files"
label = "Download selected files"
fields = ["repo_id", "filenames", "include", "exclude", "local_dir"]
required = ["repo_id"]

[[commands.subcommand.task]]
id = "preview"
label = "Preview a download"
fields = ["repo_id", "repo_type", "dry_run"]
required = ["repo_id"]
set = { dry_run = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["repo_id", "filenames", "repo_type", "revision", "local_dir", "dry_run"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["include", "exclude", "cache_dir"]