Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,10 +102,8 @@ The `huggingface_hub` library allows you to interact with the [Hugging Face Hub]
The `hf` CLI is designed for people and coding agents alike: the same commands adapt their output when run by an agent. If you use Claude Code, Codex, Cursor, or another coding agent, install the `hf` CLI Skill — a command reference generated from your installed CLI:

```bash
# for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add
# includes the above + Claude Code
hf skills add --claude
```

Learn more in the [Hugging Face CLI for AI agents guide](https://huggingface.co/docs/hub/agents-cli) and the [announcement blog post](https://huggingface.co/blog/hf-cli-for-agents).
Expand Down
6 changes: 2 additions & 4 deletions docs/source/en/guides/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,8 @@ The `huggingface_hub` Python package comes with a built-in CLI called `hf`. This
> [!TIP]
> Using the `hf` CLI with AI agents? Install the Skill and check out the [Hugging Face CLI for AI Agents](https://huggingface.co/docs/hub/agents-cli) guide.
> ```bash
> # for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
> # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
> hf skills add
> # includes the above + Claude Code
> hf skills add --claude
> ```
> The standalone installer installs it for you (see below), and `hf update` refreshes it.

Expand Down Expand Up @@ -2390,7 +2388,7 @@ Or create a webhook that triggers a Job instead:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-c
```

The `--watch` option uses the format `type:name` where type is one of `model`, `dataset`, `space`, `org`, or `user`. It can be repeated to watch multiple items. Use `--domain` to filter events to `repo` or `discussions`, and `--secret` to set a signing secret.
The `--watch` option uses the format `type:name` where type is one of `model`, `dataset`, `space`, `bucket`, `org`, or `user`. It can be repeated to watch multiple items. Use `--domain` to filter events to `repo` or `discussions`, and `--secret` to set a signing secret.

### Update a webhook

Expand Down
12 changes: 6 additions & 6 deletions docs/source/en/package_reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -4293,7 +4293,8 @@ Install a Hugging Face skill for an AI assistant.
The default `hf-cli` skill is generated locally from the installed CLI version;
other skills are downloaded from the Hugging Face marketplace.
Default location is in the current directory (.agents/skills) or user-level (~/.agents/skills).
If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory.
The skill is also symlinked into Claude Code's skills directory (`.claude/skills` or `~/.claude/skills`,
honoring `CLAUDE_CONFIG_DIR` when set), unless `--dest` is used.

**Usage**:

Expand All @@ -4307,7 +4308,7 @@ $ hf skills add [OPTIONS] [NAME]

**Options**:

* `--claude`: Install for Claude.
* `--claude`: (Deprecated) No longer needed: skills are always installed for Claude Code too.
* `-g, --global`: Install globally (user-level) instead of in the current project directory.
* `--dest PATH`: Install into a custom destination (path to skills directory).
* `--force`: Overwrite existing skills in the destination.
Expand All @@ -4317,8 +4318,7 @@ Examples
$ hf skills add
$ hf skills add huggingface-gradio --dest=~/my-skills
$ hf skills add --global
$ hf skills add --claude
$ hf skills add huggingface-gradio --claude --global
$ hf skills add huggingface-gradio --global

Learn more
Use `hf <command> --help` for more information about a command.
Expand Down Expand Up @@ -4379,7 +4379,7 @@ $ hf skills update [OPTIONS] [NAME]

**Options**:

* `--claude`: Update skills installed for Claude.
* `--claude`: (Deprecated) No longer needed: skills are always installed for Claude Code too.
* `-g, --global`: Use global skills directories instead of the current project.
* `--dest PATH`: Update skills in a custom skills directory.
* `--help`: Show this message and exit.
Expand All @@ -4388,7 +4388,7 @@ Examples
$ hf skills update
$ hf skills update hf-cli
$ hf skills update huggingface-gradio --dest=~/my-skills
$ hf skills update --claude
$ hf skills update -g

Learn more
Use `hf <command> --help` for more information about a command.
Expand Down
4 changes: 1 addition & 3 deletions docs/source/en/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,8 @@ For more details, check out the [installation](installation) guide.
> The `huggingface_hub` also ships with a [`hf` CLI](./guides/cli) that lets you interact with the Hub directly from the terminal.
> If you're using AI agents (Claude Code, Codex, Cursor, ...), install the Skill to let your agent use the CLI:
> ```bash
> # for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
> # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
> hf skills add
> # includes the above + Claude Code
> hf skills add --claude
> ```
> Check out the [Hugging Face CLI for AI Agents](https://huggingface.co/docs/hub/agents-cli) guide for more details.

Expand Down
2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ def get_version() -> str:

extras["hf_xet"] = [HF_XET_VERSION]

extras["mcp"] = ["mcp>=1.8.0, <2.0.0"]
extras["mcp"] = ["mcp>=1.9.4, <2.0.0"] # list_tools(cursor=...) only paginates correctly from 1.9.4

extras["testing"] = (
extras["oauth"]
Expand Down
8 changes: 4 additions & 4 deletions src/huggingface_hub/cli/_skills.py
Original file line number Diff line number Diff line change
Expand Up @@ -356,21 +356,21 @@ def _check_skill_update() -> None:
if any(tag in __version__ for tag in ["rc", "dev"]):
return
out.hint(
f"The `{DEFAULT_SKILL_ID}` skill is not installed. Run `hf skills add -g --claude`"
f"The `{DEFAULT_SKILL_ID}` skill is not installed. Run `hf skills add -g`"
" to teach your AI agents how to use the `hf` CLI."
)
return

# Suggest the command matching where the outdated skill is installed (global takes precedence).
if any(_is_skill_outdated(skill_dir) for skill_dir in global_dirs):
scope = "-g --claude"
scope = " -g"
elif any(_is_skill_outdated(skill_dir) for skill_dir in local_dirs):
scope = "--claude"
scope = ""
else:
return
out.hint(
f"The installed `{DEFAULT_SKILL_ID}` skill was generated by another `hf` version."
f" Run `hf skills update {DEFAULT_SKILL_ID} {scope}` to refresh it."
f" Run `hf skills update {DEFAULT_SKILL_ID}{scope}` to refresh it."
)


Expand Down
61 changes: 36 additions & 25 deletions src/huggingface_hub/cli/skills.py
Original file line number Diff line number Diff line change
Expand Up @@ -330,6 +330,12 @@ def _install_to(skills_dir: Path, skill_name: str, force: bool) -> Path:
raise CLIError(f"{exc}\nRe-run with --force to overwrite.") from exc


_CLAUDE_FLAG_DEPRECATED = (
"`--claude` is deprecated and will be removed in a future release:"
" skills are always installed for Claude Code too."
)


def _create_symlink(agent_skills_dir: Path, skill_name: str, central_skill_path: Path, force: bool) -> Path:
"""Create a relative symlink from agent directory to the central skill location."""
agent_skills_dir = agent_skills_dir.expanduser().resolve()
Expand All @@ -347,20 +353,16 @@ def _create_symlink(agent_skills_dir: Path, skill_name: str, central_skill_path:
return link_path


def _resolve_update_roots(
*,
claude: bool,
global_: bool,
dest: Path | None,
) -> list[Path]:
def _resolve_update_roots(*, global_: bool, dest: Path | None) -> list[Path]:
if dest is not None:
if claude or global_:
raise CLIError("--dest cannot be combined with --claude or --global.")
if global_:
raise CLIError("--dest cannot be combined with --global.")
return [dest.expanduser().resolve()]

roots: list[Path] = [constants.AGENTS_SKILLS_GLOBAL_PATH if global_ else constants.AGENTS_SKILLS_LOCAL_PATH]
if claude:
roots.append(constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH)
if global_:
roots = [constants.AGENTS_SKILLS_GLOBAL_PATH, constants.CLAUDE_SKILLS_GLOBAL_PATH]
else:
roots = [constants.AGENTS_SKILLS_LOCAL_PATH, constants.CLAUDE_SKILLS_LOCAL_PATH]
return [root.expanduser().resolve() for root in roots]


Expand Down Expand Up @@ -419,16 +421,18 @@ def skills_list(
"hf skills add",
"hf skills add huggingface-gradio --dest=~/my-skills",
"hf skills add --global",
"hf skills add --claude",
"hf skills add huggingface-gradio --claude --global",
"hf skills add huggingface-gradio --global",
],
)
def skills_add(
name: Annotated[
str,
Argument(help="Marketplace skill name.", show_default=False),
] = DEFAULT_SKILL_ID,
claude: Annotated[bool, Option("--claude", help="Install for Claude.")] = False,
claude: Annotated[
bool,
Option("--claude", help="(Deprecated) No longer needed: skills are always installed for Claude Code too."),
] = False,
global_: Annotated[
bool,
Option(
Expand Down Expand Up @@ -456,24 +460,26 @@ def skills_add(
The default `hf-cli` skill is generated locally from the installed CLI version;
other skills are downloaded from the Hugging Face marketplace.
Default location is in the current directory (.agents/skills) or user-level (~/.agents/skills).
If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory.
The skill is also symlinked into Claude Code's skills directory (`.claude/skills` or `~/.claude/skills`,
honoring `CLAUDE_CONFIG_DIR` when set), unless `--dest` is used.
"""
if claude:
out.warning(_CLAUDE_FLAG_DEPRECATED)
if dest is not None:
if claude or global_:
raise CLIError("--dest cannot be combined with --claude or --global.")
if global_:
raise CLIError("--dest cannot be combined with --global.")
skill_dest = _install_to(dest, name, force)
print(f"Installed '{name}' to {skill_dest}")
return

# Install to central location
# Install to central location, then expose it to Claude Code which only reads `.claude/skills`
central_path = constants.AGENTS_SKILLS_GLOBAL_PATH if global_ else constants.AGENTS_SKILLS_LOCAL_PATH
central_skill_path = _install_to(central_path, name, force)
print(f"Installed '{name}' to central location: {central_skill_path}")

if claude:
agent_target = constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH
link_path = _create_symlink(agent_target, name, central_skill_path, force)
print(f"Created symlink: {link_path}" if link_path.is_symlink() else f"Copied '{name}' to {link_path}")
claude_path = constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH
link_path = _create_symlink(claude_path, name, central_skill_path, force)
print(f"Created symlink: {link_path}" if link_path.is_symlink() else f"Copied '{name}' to {link_path}")


@skills_cli.command(
Expand All @@ -482,15 +488,18 @@ def skills_add(
"hf skills update",
"hf skills update hf-cli",
"hf skills update huggingface-gradio --dest=~/my-skills",
"hf skills update --claude",
"hf skills update -g",
],
)
def skills_update(
name: Annotated[
str | None,
Argument(help="Optional installed skill name to update.", show_default=False),
] = None,
claude: Annotated[bool, Option("--claude", help="Update skills installed for Claude.")] = False,
claude: Annotated[
bool,
Option("--claude", help="(Deprecated) No longer needed: skills are always installed for Claude Code too."),
] = False,
global_: Annotated[
bool,
Option(
Expand All @@ -507,7 +516,9 @@ def skills_update(
] = None,
) -> None:
"""Update installed Hugging Face marketplace skills."""
roots = _resolve_update_roots(claude=claude, global_=global_, dest=dest)
if claude:
out.warning(_CLAUDE_FLAG_DEPRECATED)
roots = _resolve_update_roots(global_=global_, dest=dest)

results = _skills.update_skills(roots, selector=name, hf_cli_content=build_skill_md())
if not results:
Expand Down
4 changes: 2 additions & 2 deletions src/huggingface_hub/cli/system.py
Original file line number Diff line number Diff line change
Expand Up @@ -71,14 +71,14 @@ def update() -> None:
raise click.exceptions.Exit(code=returncode)

if not skill_installed:
out.hint("Run `hf skills add -g --claude` to teach your AI agents how to use the `hf` CLI.")
out.hint("Run `hf skills add -g` to teach your AI agents how to use the `hf` CLI.")
return

# Refresh the globally installed skill so agents see the new command surface. Runs in a
# subprocess: the skill is generated from the CLI code, which has just been replaced on disk
# while this process still runs the previous version.
out.text(f"Updating the `{DEFAULT_SKILL_ID}` skill...")
subprocess.call([*_hf_argv(), "skills", "update", DEFAULT_SKILL_ID, "-g", "--claude"])
subprocess.call([*_hf_argv(), "skills", "update", DEFAULT_SKILL_ID, "-g"])


def _hf_argv() -> list[str]:
Expand Down
3 changes: 2 additions & 1 deletion src/huggingface_hub/constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -227,10 +227,11 @@ def list_files(repo_id: str):

# Skills directories for AI agents: `.agents/skills` is read by most agents, `.claude/skills` by Claude Code.
# Local = current project, global = user-level (see `hf skills add`).
# Claude Code's user-level directory defaults to `~/.claude` but can be relocated with `CLAUDE_CONFIG_DIR`.
AGENTS_SKILLS_LOCAL_PATH = Path(".agents/skills")
AGENTS_SKILLS_GLOBAL_PATH = Path("~/.agents/skills")
CLAUDE_SKILLS_LOCAL_PATH = Path(".claude/skills")
CLAUDE_SKILLS_GLOBAL_PATH = Path("~/.claude/skills")
CLAUDE_SKILLS_GLOBAL_PATH = Path(os.environ.get("CLAUDE_CONFIG_DIR") or "~/.claude") / "skills"

# Set to skip the CLI update check (PyPI query + "new version available" warning at startup).
HF_HUB_DISABLE_UPDATE_CHECK = _is_true(os.environ.get("HF_HUB_DISABLE_UPDATE_CHECK"))
Expand Down
15 changes: 8 additions & 7 deletions src/huggingface_hub/hf_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -455,13 +455,14 @@ class WebhookWatchedItem:
"""Data structure containing information about the items watched by a webhook.

Attributes:
type (`Literal["dataset", "model", "org", "space", "user"]`):
Type of the item to be watched. Can be one of `["dataset", "model", "org", "space", "user"]`.
type (`Literal["bucket", "dataset", "model", "org", "space", "user"]`):
Type of the item to be watched. Can be one of `["bucket", "dataset", "model", "org", "space", "user"]`.
name (`str`):
Name of the item to be watched. Can be the username, organization name, model name, dataset name or space name.
Name of the item to be watched. Can be the username, organization name, model name, dataset name, space name
or bucket name.
"""

type: Literal["dataset", "model", "org", "space", "user"]
type: Literal["bucket", "dataset", "model", "org", "space", "user"]
name: str


Expand Down Expand Up @@ -10783,7 +10784,7 @@ def create_webhook(
ID of the source Job to trigger with the webhook payload in the environment variable WEBHOOK_PAYLOAD.
Additional environment variables are available for convenience: WEBHOOK_REPO_ID, WEBHOOK_REPO_TYPE and WEBHOOK_SECRET.
watched (`list[WebhookWatchedItem]`):
List of [`WebhookWatchedItem`] to be watched by the webhook. It can be users, orgs, models, datasets or spaces.
List of [`WebhookWatchedItem`] to be watched by the webhook. It can be users, orgs, models, datasets, spaces or buckets.
Watched items can also be provided as plain dictionaries.
domains (`list[Literal["repo", "discussion"]]`, optional):
List of domains to watch. It can be "repo", "discussion" or both.
Expand Down Expand Up @@ -12311,7 +12312,7 @@ def update_job_labels(
labels (`dict[str, str]`):
New labels to set on the job. Replaces all existing labels.
Both keys and values must be max 100 characters and contain only
alphanumeric characters, dots, dashes, and underscores.
alphanumeric characters, dashes, and underscores.

namespace (`str`, *optional*):
The namespace where the Job is running. Defaults to the current user's namespace.
Expand Down Expand Up @@ -12915,7 +12916,7 @@ def update_scheduled_job_labels(
labels (`dict[str, str]`):
New labels to set on the scheduled job. Replaces all existing labels.
Both keys and values must be max 100 characters and contain only
alphanumeric characters, dots, dashes, and underscores.
alphanumeric characters, dashes, and underscores.

namespace (`str`, *optional*):
The namespace where the scheduled Job is. Defaults to the current user's namespace.
Expand Down
21 changes: 8 additions & 13 deletions src/huggingface_hub/hf_file_system.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
from dataclasses import dataclass, field
from datetime import datetime
from itertools import chain
from pathlib import Path, PurePosixPath
from pathlib import PurePosixPath
from typing import Any, NoReturn, Union
from urllib.parse import quote, unquote

Expand Down Expand Up @@ -1088,7 +1088,7 @@ def get_file(self, rpath, lpath=None, callback=_DEFAULT_CALLBACK, outfile=None,
rpath (`str`):
Remote path to download from.
lpath (`str`, *optional*):
Local path to download to. Not required when `outfile` is provided.
Local path to download to. Can be omitted if `outfile` is provided.
callback (`Callback`, *optional*):
Optional callback to track download progress. Defaults to no callback.
outfile (`IO`, *optional*):
Expand All @@ -1106,7 +1106,8 @@ def get_file(self, rpath, lpath=None, callback=_DEFAULT_CALLBACK, outfile=None,
# and let's not handle custom kwargs
return super().get_file(rpath, lpath, callback=callback, outfile=outfile, **kwargs)

# Taken from https://github.com/fsspec/filesystem_spec/blob/47b445ae4c284a82dd15e0287b1ffc410e8fc470/fsspec/spec.py#L883
# Adapted from https://github.com/fsspec/filesystem_spec/blob/0f76baaae4a227b085b18e8469e6cc1792a95ade/fsspec/spec.py#L975
close_file = False
if outfile is None:
if lpath is None:
raise ValueError("Either `lpath` or `outfile` must be provided.")
Expand All @@ -1115,16 +1116,10 @@ def get_file(self, rpath, lpath=None, callback=_DEFAULT_CALLBACK, outfile=None,
elif self.isdir(rpath):
os.makedirs(lpath, exist_ok=True)
return None

if isinstance(lpath, (str, Path)): # otherwise, let's assume it's a file-like object
os.makedirs(os.path.dirname(lpath), exist_ok=True)

# Open file if not already open
close_file = False
if outfile is None:
assert lpath is not None
outfile = open(lpath, "wb")
close_file = True
else:
os.makedirs(os.path.dirname(lpath), exist_ok=True)
outfile = open(lpath, "wb")
close_file = True
initial_pos = outfile.tell()

# Custom implementation of `get_file` to use `http_get`.
Expand Down
Loading
Loading