[CLI] Add 'hf repo list' command with filtering and sorting

Author: akshatvishu

docs/source/en/package_reference/cli.md

@@ -1003,6 +1003,7 @@ $ hf repo [OPTIONS] COMMAND [ARGS]...
 * `branch`: Manage branches for a repo on the Hub.
 * `create`: Create a new repo on the Hub.
 * `delete`: Delete a repo from the Hub.
+* `list`: List repositories (models, datasets,...
 * `move`: Move a repository from a namespace to...
 * `settings`: Update the settings of a repository.
 * `tag`: Manage tags for a repo on the Hub.
@@ -1115,6 +1116,27 @@ $ hf repo delete [OPTIONS] REPO_ID
 * `--missing-ok / --no-missing-ok`: If set to True, do not raise an error if repo does not exist.  [default: no-missing-ok]
 * `--help`: Show this message and exit.
 
+### `hf repo list`
+
+List repositories (models, datasets, spaces) hosted on the Hub.
+
+**Usage**:
+
+```console
+$ hf repo list [OPTIONS]
+```
+
+**Options**:
+
+* `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space).  [default: model]
+* `--limit INTEGER`: Limit the number of results.  [default: 10]
+* `--filter TEXT`: Filter by tags (e.g. 'text-classification'). Can be used multiple times.
+* `--search TEXT`: Search by name.
+* `--author TEXT`: Filter by author or organization.
+* `--sort TEXT`: Sort results key, optionally with direction (e.g. 'likes', 'downloads:asc').
+* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
+* `--help`: Show this message and exit.
+
 ### `hf repo move`
 
 Move a repository from a namespace to another namespace.

src/huggingface_hub/cli/repo.py

@@ -22,6 +22,9 @@
 """
 
 import enum
+import json
+import re
+from datetime import timezone
 from typing import Annotated, Optional
 
 import typer
@@ -43,6 +46,8 @@
 
 logger = logging.get_logger(__name__)
 
+_SORT_PATTERN = re.compile(r"^(?P<key>[a-zA-Z0-9_-]+)(?::(?P<order>asc|desc))?$")
+
 repo_cli = typer_factory(help="Manage repos on the Hub.")
 tag_cli = typer_factory(help="Manage tags for a repo on the Hub.")
 branch_cli = typer_factory(help="Manage branches for a repo on the Hub.")
@@ -160,6 +165,92 @@ def repo_settings(
     print(f"Successfully updated the settings of {ANSI.bold(repo_id)} on the Hub.")
 
 
+@repo_cli.command("list", help="List repositories (models, datasets, spaces) hosted on the Hub.")
+def repo_list(
+    repo_type: RepoTypeOpt = RepoType.model,
+    limit: Annotated[int, typer.Option(help="Limit the number of results.")] = 10,
+    filter: Annotated[
+        Optional[list[str]],
+        typer.Option(help="Filter by tags (e.g. 'text-classification'). Can be used multiple times."),
+    ] = None,
+    search: Annotated[Optional[str], typer.Option(help="Search by name.")] = None,
+    author: Annotated[Optional[str], typer.Option(help="Filter by author or organization.")] = None,
+    sort: Annotated[
+        Optional[str],
+        typer.Option(help="Sort results key, optionally with direction (e.g. 'likes', 'downloads:asc')."),
+    ] = None,
+    token: TokenOpt = None,
+) -> None:
+    api = get_hf_api(token=token)
+
+    sort_key = None
+    direction = None
+
+    if sort:
+        match = _SORT_PATTERN.match(sort)
+        if not match:
+            typer.echo(
+                f"Error: Invalid sort format '{sort}'. Expected 'field' or 'field:direction' (e.g. 'downloads:desc')."
+            )
+            raise typer.Exit(1)
+
+        sort_key = match.group("key")
+        order = match.group("order")
+
+        if order == "desc":
+            direction = -1
+
+    output_data = []
+
+    try:
+        if repo_type == RepoType.model:
+            list_method = api.list_models
+        elif repo_type == RepoType.dataset:
+            list_method = api.list_datasets
+        elif repo_type == RepoType.space:
+            list_method = api.list_spaces
+
+        results = list_method(
+            filter=filter,
+            author=author,
+            search=search,
+            sort=sort_key,
+            direction=direction,
+            limit=limit,
+        )
+
+        for repo in results:
+            created_at_str = None
+            if getattr(repo, "created_at", None):
+                dt = repo.created_at
+                if dt.tzinfo:
+                    dt = dt.astimezone(timezone.utc)
+                created_at_str = dt.isoformat().replace("+00:00", "Z")
+
+            item = {
+                "id": repo.id,
+                "downloads": getattr(repo, "downloads", 0),
+                "likes": getattr(repo, "likes", 0),
+                "trendingScore": getattr(repo, "trending_score", None),
+                "createdAt": created_at_str,
+                "private": getattr(repo, "private", False),
+            }
+
+            if hasattr(repo, "pipeline_tag") and repo.pipeline_tag:
+                item["pipeline_tag"] = repo.pipeline_tag
+
+            if hasattr(repo, "library_name") and repo.library_name:
+                item["library_name"] = repo.library_name
+
+            output_data.append(item)
+
+    except Exception as e:
+        typer.echo(f"Error fetching {repo_type.value}s: {e}")
+        raise typer.Exit(1)
+
+    typer.echo(json.dumps(output_data, indent=2))
+
+
 @branch_cli.command("create", help="Create a new branch for a repo on the Hub.")
 def branch_create(
     repo_id: RepoIdArg,

tests/test_cli.py

@@ -1265,6 +1265,103 @@ def test_repo_delete_with_all_options(self, runner: CliRunner) -> None:
         )
 
 
+class TestRepoListCommand:
+    def test_repo_list_basic(self, runner: CliRunner) -> None:
+        """Test basic listing of models with defaults and JSON output verification."""
+        from datetime import datetime, timezone
+
+        # Mock a repo object (simulating ModelInfo)
+        repo = Mock()
+        repo.id = "user/model-id"
+        repo.downloads = 100
+        repo.likes = 50
+        repo.trending_score = 10
+        repo.created_at = datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc)
+        repo.private = False
+        repo.pipeline_tag = "text-classification"
+        repo.library_name = "transformers"
+
+        with patch("huggingface_hub.cli.repo.get_hf_api") as api_cls:
+            api = api_cls.return_value
+            api.list_models.return_value = iter([repo])
+
+            result = runner.invoke(app, ["repo", "list"])
+
+        assert result.exit_code == 0
+        api_cls.assert_called_once_with(token=None)
+
+        # Verify API was called with correct default arguments
+        api.list_models.assert_called_once()
+        _, kwargs = api.list_models.call_args
+        assert kwargs["limit"] == 10
+        assert kwargs["sort"] is None
+
+        # Verify JSON output
+        output = json.loads(result.stdout)
+        assert len(output) == 1
+        assert output[0]["id"] == "user/model-id"
+        assert output[0]["createdAt"] == "2024-01-01T12:00:00Z"
+        assert output[0]["pipeline_tag"] == "text-classification"
+
+    def test_repo_list_sorting_parsing(self, runner: CliRunner) -> None:
+        """Test that 'downloads:asc' is correctly parsed into sort='downloads', direction=1."""
+        with patch("huggingface_hub.cli.repo.get_hf_api") as api_cls:
+            api = api_cls.return_value
+            api.list_models.return_value = iter([])
+
+            # Test Ascending
+            result = runner.invoke(app, ["repo", "list", "--sort", "downloads:asc"])
+            assert result.exit_code == 0
+            _, kwargs = api.list_models.call_args
+            assert kwargs["sort"] == "downloads"
+            assert kwargs["direction"] == 1
+
+            # Test Descending
+            result = runner.invoke(app, ["repo", "list", "--sort", "likes:desc"])
+            assert result.exit_code == 0
+            _, kwargs = api.list_models.call_args
+            assert kwargs["sort"] == "likes"
+            assert kwargs["direction"] == -1
+
+    def test_repo_list_datasets_with_filter(self, runner: CliRunner) -> None:
+        """Test listing datasets with multiple filters."""
+        with patch("huggingface_hub.cli.repo.get_hf_api") as api_cls:
+            api = api_cls.return_value
+            api.list_datasets.return_value = iter([])
+
+            result = runner.invoke(
+                app, ["repo", "list", "--repo-type", "dataset", "--filter", "text-classification", "--filter", "en"]
+            )
+
+        assert result.exit_code == 0
+        api.list_datasets.assert_called_once()
+        _, kwargs = api.list_datasets.call_args
+        # Typer passes multiple --filter flags as a list
+        assert kwargs["filter"] == ["text-classification", "en"]
+
+    def test_repo_list_invalid_sort(self, runner: CliRunner) -> None:
+        """Test that invalid sort string raises a user-friendly error."""
+        result = runner.invoke(app, ["repo", "list", "--sort", "bad:format:here"])
+        assert result.exit_code == 1
+        assert "Error: Invalid sort format" in result.stdout
+
+    def test_repo_list_api_error_handling(self, runner: CliRunner) -> None:
+        """Test graceful handling of API errors (like BadRequest during iteration)."""
+        with patch("huggingface_hub.cli.repo.get_hf_api") as api_cls:
+            api = api_cls.return_value
+
+            def error_generator(**kwargs):
+                raise Exception("Invalid sort direction")
+                yield
+
+            api.list_models.side_effect = error_generator
+
+            result = runner.invoke(app, ["repo", "list"])
+
+        assert result.exit_code == 1
+        assert "Error fetching models" in result.stdout
+
+
 class TestInferenceEndpointsCommands:
     def test_list(self, runner: CliRunner) -> None:
         endpoint = Mock(raw={"name": "demo"})