Skip to content

Commit f148666

Browse files
[CLI] Fix truncated command descriptions in the CLI reference (#4849)
1 parent c4f076c commit f148666

3 files changed

Lines changed: 85 additions & 65 deletions

File tree

‎docs/source/en/package_reference/cli.md‎

Lines changed: 63 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -27,26 +27,26 @@ $ hf [OPTIONS] [COMMAND] [ARGS]...
2727
* `buckets`: Commands to interact with buckets.
2828
* `cache`: Manage local cache directory.
2929
* `collections`: Interact with collections on the Hub.
30-
* `cp`: Copy files between local paths,...
30+
* `cp`: Copy files between local paths, repositories, and buckets.
3131
* `datasets`: Interact with datasets on the Hub.
32-
* `discussions`: Manage discussions and pull requests on...
32+
* `discussions`: Manage discussions and pull requests on the Hub.
3333
* `download`: Download files from the Hub.
3434
* `endpoints`: Manage Hugging Face Inference Endpoints.
3535
* `env`: Print information about the environment.
3636
* `extensions`: Manage hf CLI extensions. [alias: ext]
3737
* `jobs`: Run and manage Jobs on the Hub.
38-
* `lfs-enable-largefiles`: Configure your repository to enable upload...
39-
* `lfs-multipart-upload`: Internal git-lfs custom transfer agent for...
38+
* `lfs-enable-largefiles`: Configure your repository to enable upload of files > 5GB.
39+
* `lfs-multipart-upload`: Internal git-lfs custom transfer agent for multipart uploads.
4040
* `models`: Interact with models on the Hub.
4141
* `papers`: Interact with papers on the Hub.
4242
* `repos`: Manage repos on the Hub. [alias: repo]
43-
* `sandbox`: Run and manage experimental sandboxes on...
43+
* `sandbox`: Run and manage experimental sandboxes on Hugging Face Jobs.
4444
* `skills`: Manage skills for AI assistants.
4545
* `spaces`: Interact with spaces on the Hub.
46-
* `sync`: Sync files between local directory and a...
46+
* `sync`: Sync files between local directory and a bucket.
4747
* `update`: Update the `hf` CLI to the latest version.
4848
* `upload`: Upload a file or a folder to the Hub.
49-
* `upload-large-folder`: [Deprecated] Upload a large folder to the...
49+
* `upload-large-folder`: [Deprecated] Upload a large folder to the Hub.
5050
* `version`: Print information about the hf version.
5151
* `webhooks`: Manage webhooks on the Hub.
5252

@@ -67,11 +67,11 @@ $ hf auth [OPTIONS] COMMAND [ARGS]...
6767
**Commands**:
6868

6969
* `list`: List all stored access tokens. [alias: ls]
70-
* `login`: Login from your browser, or using a token...
70+
* `login`: Login from your browser, or using a token from huggingface.co/settings/tokens.
7171
* `logout`: Logout from a specific token.
7272
* `switch`: Switch between access tokens.
7373
* `token`: Print the current access token to stdout.
74-
* `whoami`: Find out which huggingface.co account you...
74+
* `whoami`: Find out which huggingface.co account you are logged in as.
7575

7676
### `hf auth list`
7777

@@ -234,15 +234,15 @@ $ hf buckets [OPTIONS] COMMAND [ARGS]...
234234

235235
**Commands**:
236236

237-
* `cp`: Copy files between local paths,...
237+
* `cp`: Copy files between local paths, repositories, and buckets.
238238
* `create`: Create a new bucket.
239239
* `delete`: Delete a bucket.
240240
* `info`: Get info about a bucket.
241241
* `list`: List buckets or files in a bucket. [alias: ls]
242-
* `move`: Move (rename) a bucket to a new name or...
242+
* `move`: Move (rename) a bucket to a new name or namespace.
243243
* `remove`: Remove files from a bucket. [alias: rm]
244244
* `settings`: Update bucket settings (visibility).
245-
* `sync`: Sync files between local directory and a...
245+
* `sync`: Sync files between local directory and a bucket.
246246

247247
### `hf buckets cp`
248248

@@ -588,9 +588,9 @@ $ hf cache [OPTIONS] COMMAND [ARGS]...
588588
**Commands**:
589589

590590
* `list`: List cached repositories or revisions. [alias: ls]
591-
* `prune`: Remove detached revisions and incomplete...
591+
* `prune`: Remove detached revisions and incomplete downloads from the cache.
592592
* `rm`: Remove cached repositories or revisions.
593-
* `verify`: Verify checksums for a single repo...
593+
* `verify`: Verify checksums for a single repo revision from cache or a local directory.
594594

595595
### `hf cache list`
596596

@@ -1044,12 +1044,12 @@ $ hf datasets [OPTIONS] COMMAND [ARGS]...
10441044

10451045
**Commands**:
10461046

1047-
* `card`: Get the dataset card (README) for a...
1047+
* `card`: Get the dataset card (README) for a dataset on the Hub.
10481048
* `info`: Get info about a dataset on the Hub.
10491049
* `leaderboard`: List model scores from a dataset leaderboard.
1050-
* `list`: List datasets on the Hub, or files in a... [alias: ls]
1051-
* `parquet`: List parquet file URLs available for a...
1052-
* `sql`: Execute a raw SQL query with DuckDB...
1050+
* `list`: List datasets on the Hub, or files in a dataset repo. [alias: ls]
1051+
* `parquet`: List parquet file URLs available for a dataset.
1052+
* `sql`: Execute a raw SQL query with DuckDB against dataset parquet URLs.
10531053

10541054
### `hf datasets card`
10551055

@@ -1267,9 +1267,9 @@ $ hf discussions [OPTIONS] COMMAND [ARGS]...
12671267

12681268
* `close`: Close a discussion or pull request.
12691269
* `comment`: Comment on a discussion or pull request.
1270-
* `create`: Create a new discussion or pull request on...
1270+
* `create`: Create a new discussion or pull request on a repo.
12711271
* `diff`: Show the diff of a pull request.
1272-
* `edit`: Edit an existing comment on a discussion...
1272+
* `edit`: Edit an existing comment on a discussion or pull request.
12731273
* `info`: Get info about a discussion or pull request.
12741274
* `list`: List discussions and pull requests on a repo. [alias: ls]
12751275
* `merge`: Merge a pull request.
@@ -1654,12 +1654,12 @@ $ hf endpoints [OPTIONS] COMMAND [ARGS]...
16541654

16551655
**Commands**:
16561656

1657-
* `catalog`: Interact with the Inference Endpoints...
1657+
* `catalog`: Interact with the Inference Endpoints catalog.
16581658
* `delete`: Delete an Inference Endpoint permanently.
1659-
* `deploy`: Deploy an Inference Endpoint from a Hub...
1659+
* `deploy`: Deploy an Inference Endpoint from a Hub repository.
16601660
* `describe`: Get information about an existing endpoint.
1661-
* `hardware`: List the hardware available to deploy an...
1662-
* `list`: Lists all Inference Endpoints for the... [alias: ls]
1661+
* `hardware`: List the hardware available to deploy an Inference Endpoint on.
1662+
* `list`: Lists all Inference Endpoints for the given namespace. [alias: ls]
16631663
* `list-catalog`: List available Catalog models.
16641664
* `pause`: Pause an Inference Endpoint.
16651665
* `resume`: Resume an Inference Endpoint.
@@ -1682,7 +1682,7 @@ $ hf endpoints catalog [OPTIONS] COMMAND [ARGS]...
16821682

16831683
**Commands**:
16841684

1685-
* `deploy`: Deploy an Inference Endpoint from the...
1685+
* `deploy`: Deploy an Inference Endpoint from the Model Catalog.
16861686
* `list`: List available Catalog models. [alias: ls]
16871687

16881688
#### `hf endpoints catalog deploy`
@@ -2095,11 +2095,11 @@ $ hf extensions [OPTIONS] COMMAND [ARGS]...
20952095
**Commands**:
20962096

20972097
* `exec`: Execute an installed extension.
2098-
* `install`: Install an extension from a public GitHub...
2098+
* `install`: Install an extension from a public GitHub repository.
20992099
* `list`: List installed extension commands. [alias: ls]
21002100
* `remove`: Remove an installed extension. [alias: rm]
2101-
* `search`: Search extensions available on GitHub...
2102-
* `update`: Update installed extension(s) to their...
2101+
* `search`: Search extensions available on GitHub (tagged with 'hf-extension' topic).
2102+
* `update`: Update installed extension(s) to their latest version.
21032103

21042104
### `hf extensions exec`
21052105

@@ -2276,16 +2276,16 @@ $ hf jobs [OPTIONS] COMMAND [ARGS]...
22762276

22772277
* `cancel`: Cancel a Job
22782278
* `hardware`: List available hardware options for Jobs
2279-
* `inspect`: Display detailed information on one or...
2279+
* `inspect`: Display detailed information on one or more Jobs
22802280
* `labels`: Update labels on a Job.
22812281
* `list`: List Jobs. [alias: ls, ps]
22822282
* `logs`: Fetch the logs of a Job.
22832283
* `run`: Run a Job.
22842284
* `scheduled`: Create and manage scheduled Jobs on the Hub.
22852285
* `ssh`: SSH into a running Job.
2286-
* `stats`: Fetch the resource usage statistics and...
2287-
* `uv`: Run UV scripts (Python with inline...
2288-
* `wait`: Wait for one or more Jobs to reach a...
2286+
* `stats`: Fetch the resource usage statistics and metrics of Jobs
2287+
* `uv`: Run UV scripts (Python with inline dependencies) on HF infrastructure.
2288+
* `wait`: Wait for one or more Jobs to reach a terminal state.
22892289

22902290
### `hf jobs cancel`
22912291

@@ -2541,13 +2541,13 @@ $ hf jobs scheduled [OPTIONS] COMMAND [ARGS]...
25412541
**Commands**:
25422542

25432543
* `delete`: Delete a scheduled Job.
2544-
* `inspect`: Display detailed information on one or...
2544+
* `inspect`: Display detailed information on one or more scheduled Jobs
25452545
* `labels`: Update labels on a scheduled Job.
25462546
* `list`: List scheduled Jobs. [alias: ls, ps]
25472547
* `resume`: Resume (unpause) a scheduled Job.
25482548
* `run`: Schedule a Job.
25492549
* `suspend`: Suspend (pause) a scheduled Job.
2550-
* `trigger`: Trigger a scheduled Job to run immediately...
2550+
* `trigger`: Trigger a scheduled Job to run immediately (does not change the schedule).
25512551
* `uv`: Schedule UV scripts on HF infrastructure.
25522552

25532553
#### `hf jobs scheduled delete`
@@ -2818,7 +2818,7 @@ $ hf jobs scheduled uv [OPTIONS] COMMAND [ARGS]...
28182818

28192819
**Commands**:
28202820

2821-
* `run`: Run a UV script (local file or URL) on HF...
2821+
* `run`: Run a UV script (local file or URL) on HF infrastructure
28222822

28232823
##### `hf jobs scheduled uv run`
28242824

@@ -2947,7 +2947,7 @@ $ hf jobs uv [OPTIONS] COMMAND [ARGS]...
29472947

29482948
**Commands**:
29492949

2950-
* `run`: Run a UV script (local file or URL) on HF...
2950+
* `run`: Run a UV script (local file or URL) on HF infrastructure
29512951

29522952
#### `hf jobs uv run`
29532953

@@ -3090,9 +3090,9 @@ $ hf models [OPTIONS] COMMAND [ARGS]...
30903090

30913091
**Commands**:
30923092

3093-
* `card`: Get the model card (README) for a model on...
3093+
* `card`: Get the model card (README) for a model on the Hub.
30943094
* `info`: Get info about a model on the Hub.
3095-
* `list`: List models on the Hub, or files in a... [alias: ls]
3095+
* `list`: List models on the Hub, or files in a model repo. [alias: ls]
30963096

30973097
### `hf models card`
30983098

@@ -3368,13 +3368,13 @@ $ hf repos [OPTIONS] [COMMAND] [ARGS]...
33683368
**Commands**:
33693369

33703370
* `branch`: Manage branches for a repo on the Hub.
3371-
* `cp`: Copy files between local paths,...
3371+
* `cp`: Copy files between local paths, repositories, and buckets.
33723372
* `create`: Create a new repo on the Hub.
33733373
* `delete`: Delete a repo from the Hub.
33743374
* `delete-files`: Delete files from a repo on the Hub.
3375-
* `duplicate`: Duplicate a repo on the Hub (model,...
3376-
* `list`: List all repos (models, datasets, spaces,... [alias: ls]
3377-
* `move`: Move a repository from a namespace to...
3375+
* `duplicate`: Duplicate a repo on the Hub (model, dataset, or Space).
3376+
* `list`: List all repos (models, datasets, spaces, buckets) with storage info. [alias: ls]
3377+
* `move`: Move a repository from a namespace to another namespace.
33783378
* `settings`: Update the settings of a repository.
33793379
* `tag`: Manage tags for a repo on the Hub.
33803380

@@ -3876,13 +3876,13 @@ $ hf sandbox [OPTIONS] COMMAND [ARGS]...
38763876

38773877
**Commands**:
38783878

3879-
* `cp`: Copy a file between the local machine and...
3880-
* `create`: Create a sandbox: a dedicated VM by...
3879+
* `cp`: Copy a file between the local machine and a sandbox (docker-style).
3880+
* `create`: Create a sandbox: a dedicated VM by default, or a cheap shared one with `--pool`.
38813881
* `exec`: Run a command in a sandbox, streaming output.
3882-
* `kill`: Terminate a sandbox, a whole shared host,...
3883-
* `pool`: Warm host VM pools and spawn experimental...
3884-
* `process`: List and stop background processes running...
3885-
* `spawn`: Start a long-running command in the...
3882+
* `kill`: Terminate a sandbox, a whole shared host, or everything (--all).
3883+
* `pool`: Warm host VM pools and spawn experimental shared sandboxes for workloads within the same trust boundary.
3884+
* `process`: List and stop background processes running in a sandbox.
3885+
* `spawn`: Start a long-running command in the background and return its pid (don't wait).
38863886

38873887
### `hf sandbox cp`
38883888

@@ -4046,9 +4046,9 @@ $ hf sandbox pool [OPTIONS] COMMAND [ARGS]...
40464046

40474047
**Commands**:
40484048

4049-
* `create`: Warm a pool: boot one host VM now, tagged...
4050-
* `delete`: Terminate every host VM of a pool (and... [alias: rm]
4051-
* `ls`: List running sandbox pools (grouped from... [alias: list]
4049+
* `create`: Warm a pool: boot one host VM now, tagged so it can be found later by its pool id.
4050+
* `delete`: Terminate every host VM of a pool (and therefore all its sandboxes). [alias: rm]
4051+
* `ls`: List running sandbox pools (grouped from their host VMs). [alias: list]
40524052

40534053
#### `hf sandbox pool create`
40544054

@@ -4153,8 +4153,8 @@ $ hf sandbox process [OPTIONS] COMMAND [ARGS]...
41534153

41544154
**Commands**:
41554155

4156-
* `kill`: Stop a background process running in a...
4157-
* `ls`: List the background processes running in a... [alias: list]
4156+
* `kill`: Stop a background process running in a sandbox.
4157+
* `ls`: List the background processes running in a sandbox (started with `hf sandbox spawn`). [alias: list]
41584158

41594159
#### `hf sandbox process kill`
41604160

@@ -4265,10 +4265,10 @@ $ hf skills [OPTIONS] COMMAND [ARGS]...
42654265

42664266
**Commands**:
42674267

4268-
* `add`: Install a Hugging Face skill for an AI...
4269-
* `list`: List available skills from the Hugging... [alias: ls]
4270-
* `preview`: Print the generated `hf-cli` SKILL.md to...
4271-
* `update`: Update installed Hugging Face marketplace...
4268+
* `add`: Install a Hugging Face skill for an AI assistant.
4269+
* `list`: List available skills from the Hugging Face marketplace. [alias: ls]
4270+
* `preview`: Print the generated `hf-cli` SKILL.md to stdout.
4271+
* `update`: Update installed Hugging Face marketplace skills.
42724272

42734273
### `hf skills add`
42744274

@@ -4395,21 +4395,21 @@ $ hf spaces [OPTIONS] COMMAND [ARGS]...
43954395

43964396
**Commands**:
43974397

4398-
* `card`: Get the Space card (README) for a Space on...
4398+
* `card`: Get the Space card (README) for a Space on the Hub.
43994399
* `dev-mode`: Enable or disable dev mode on a Space.
44004400
* `hardware`: List available hardware options for Spaces.
4401-
* `hot-reload`: Hot-reload any Python file of a Space...
4401+
* `hot-reload`: Hot-reload any Python file of a Space without a full rebuild + restart.
44024402
* `info`: Get info about a space on the Hub.
4403-
* `list`: List spaces on the Hub, or files in a... [alias: ls]
4403+
* `list`: List spaces on the Hub, or files in a space repo. [alias: ls]
44044404
* `logs`: Fetch the run or build logs of a Space.
44054405
* `pause`: Pause a Space.
44064406
* `restart`: Restart a Space.
4407-
* `search`: Search spaces on the Hub using semantic...
4407+
* `search`: Search spaces on the Hub using semantic search.
44084408
* `secrets`: Manage secrets for a Space on the Hub.
44094409
* `settings`: Update the settings of a Space.
44104410
* `ssh`: SSH into a Space's Dev Mode container.
44114411
* `templates`: List the available Space templates.
4412-
* `variables`: Manage environment variables for a Space...
4412+
* `variables`: Manage environment variables for a Space on the Hub.
44134413
* `volumes`: Manage volumes for a Space on the Hub.
44144414
* `wait`: Wait for a Space to finish building/starting.
44154415

@@ -4967,7 +4967,7 @@ $ hf spaces variables [OPTIONS] COMMAND [ARGS]...
49674967

49684968
**Commands**:
49694969

4970-
* `add`: Add or update environment variables for a...
4970+
* `add`: Add or update environment variables for a Space.
49714971
* `delete`: Remove an environment variable from a Space.
49724972
* `list`: List environment variables for a Space. [alias: ls]
49734973

‎tests/test_generate_cli_reference.py‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
from utils.generate_cli_reference import _normalize_command_aliases
1+
import click
2+
3+
from utils.generate_cli_reference import _normalize_command_aliases, get_docs_for_click
24

35

46
def test_normalize_nested_aliases_in_usage_lines() -> None:
@@ -39,3 +41,19 @@ def test_normalize_parent_and_child_aliases_in_usage_lines() -> None:
3941

4042
assert "$ hf extensions list [OPTIONS]" in normalized
4143
assert "$ hf extensions | ext list [OPTIONS]" not in normalized
44+
45+
46+
def test_short_help_is_not_truncated() -> None:
47+
@click.group()
48+
def cli() -> None: ...
49+
50+
@cli.command()
51+
def verify() -> None:
52+
"""Verify checksums for a single repo revision from cache or a local directory.
53+
54+
More details here.
55+
"""
56+
57+
docs = get_docs_for_click(obj=cli, ctx=click.Context(cli, info_name="hf"), name="hf")
58+
59+
assert "* `verify`: Verify checksums for a single repo revision from cache or a local directory.\n" in docs

‎utils/generate_cli_reference.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import argparse
22
import re
3+
import sys
34
from difflib import unified_diff
45
from pathlib import Path
56

@@ -63,7 +64,8 @@ def get_docs_for_click(
6364
if commands:
6465
docs += "**Commands**:\n\n"
6566
for _, sub in commands:
66-
short_help = sub.get_short_help_str()
67+
# Click's default limit is 45 chars; keep the full first sentence like `hf --help` does.
68+
short_help = sub.get_short_help_str(limit=sys.maxsize)
6769
docs += f"* `{sub.name}`" + (f": {short_help}" if short_help else "") + "\n"
6870
docs += "\n"
6971
for _, sub in commands:

0 commit comments

Comments
 (0)