feat(cli): alphabetize subcommand options and commands via SortedGroup

SortedGroup now sorts options on individual commands (not just groups)
by overriding get_command() to sort params before help rendering.

Sort order: required options first, then alphabetical by flag name,
--help always last. Commands within groups also alphabetized.

Applied to all 20 Typer() instances across 16 handler files.

374 tests pass, all linting clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: yeldarby

roboflow/cli/__init__.py

@@ -13,6 +13,7 @@
 import typer
 
 import roboflow
+from roboflow.cli._compat import SortedGroup
 
 # ---------------------------------------------------------------------------
 # Root application
@@ -27,6 +28,7 @@
 app = typer.Typer(
     name="roboflow",
     help=_DESCRIPTION,
+    cls=SortedGroup,
     pretty_exceptions_enable=False,
     rich_markup_mode="rich",
     add_completion=False,

roboflow/cli/_compat.py

@@ -11,9 +11,51 @@
 import types
 from typing import Any
 
+import click
 import typer  # noqa: TC002 — needed at runtime for Context type
 
 
+def _sort_params(params: list[click.Parameter]) -> None:
+    """Sort params in-place: required first, then alphabetical by option name."""
+    params.sort(
+        key=lambda p: (
+            # --help always last
+            "help" in (p.opts if hasattr(p, "opts") else [p.name or ""]),
+            # Required options first
+            not getattr(p, "required", False),
+            # Arguments before options (positionals first)
+            not isinstance(p, click.Argument),
+            # Alphabetical by the first long option name
+            (p.opts[0].lstrip("-") if hasattr(p, "opts") and p.opts else p.name or ""),
+        )
+    )
+
+
+class SortedGroup(typer.core.TyperGroup):
+    """Click Group that alphabetizes commands and options in --help output.
+
+    Use as ``cls=SortedGroup`` when creating Typer apps so that subcommand
+    help pages show options and commands in alphabetical order (with
+    required options first).
+    """
+
+    def list_commands(self, ctx: click.Context) -> list[str]:  # type: ignore[override]
+        return sorted(super().list_commands(ctx))
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Sort options alphabetically before rendering help."""
+        _sort_params(self.params)
+        super().format_help(ctx, formatter)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:  # type: ignore[override]
+        """Wrap returned commands to sort their options too."""
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None and not isinstance(cmd, SortedGroup):
+            # Sort the command's params for its --help output
+            _sort_params(cmd.params)
+        return cmd
+
+
 def ctx_to_args(ctx: typer.Context, **kwargs: Any) -> types.SimpleNamespace:
     """Convert a typer Context (with global opts in ``ctx.obj``) to an args namespace.
 

roboflow/cli/handlers/annotation.py

@@ -6,11 +6,11 @@
 
 import typer
 
-from roboflow.cli._compat import ctx_to_args
+from roboflow.cli._compat import SortedGroup, ctx_to_args
 
-annotation_app = typer.Typer(help="Annotation management commands", no_args_is_help=True)
-batch_app = typer.Typer(help="Annotation batch commands", no_args_is_help=True)
-job_app = typer.Typer(help="Annotation job commands", no_args_is_help=True)
+annotation_app = typer.Typer(cls=SortedGroup, help="Annotation management commands", no_args_is_help=True)
+batch_app = typer.Typer(cls=SortedGroup, help="Annotation batch commands", no_args_is_help=True)
+job_app = typer.Typer(cls=SortedGroup, help="Annotation job commands", no_args_is_help=True)
 
 annotation_app.add_typer(batch_app, name="batch")
 annotation_app.add_typer(job_app, name="job")

roboflow/cli/handlers/auth.py

@@ -6,9 +6,9 @@
 
 import typer
 
-from roboflow.cli._compat import ctx_to_args
+from roboflow.cli._compat import SortedGroup, ctx_to_args
 
-auth_app = typer.Typer(help="Manage authentication and credentials", no_args_is_help=True)
+auth_app = typer.Typer(cls=SortedGroup, help="Manage authentication and credentials", no_args_is_help=True)
 
 
 @auth_app.command("login")

roboflow/cli/handlers/batch.py

@@ -6,9 +6,9 @@
 
 import typer
 
-from roboflow.cli._compat import ctx_to_args
+from roboflow.cli._compat import SortedGroup, ctx_to_args
 
-batch_app = typer.Typer(help="Batch processing operations", no_args_is_help=True)
+batch_app = typer.Typer(cls=SortedGroup, help="Batch processing operations", no_args_is_help=True)
 
 
 def _stub(args) -> None:  # noqa: ANN001

roboflow/cli/handlers/completion.py

@@ -12,7 +12,9 @@
 import click
 import typer
 
-completion_app = typer.Typer(help="Generate shell completions", no_args_is_help=True)
+from roboflow.cli._compat import SortedGroup
+
+completion_app = typer.Typer(cls=SortedGroup, help="Generate shell completions", no_args_is_help=True)
 
 
 def _generate_completion(shell: str) -> None:

roboflow/cli/handlers/deployment.py

@@ -13,7 +13,7 @@
 
 import typer
 
-from roboflow.cli._compat import ctx_to_args
+from roboflow.cli._compat import SortedGroup, ctx_to_args
 
 # ---------------------------------------------------------------------------
 # Wrapper that captures legacy handler stdout/exit and normalises output
@@ -69,7 +69,7 @@ def _wrapped(args):  # noqa: ANN001
     return _wrapped
 
 
-deployment_app = typer.Typer(help="Manage dedicated deployments", no_args_is_help=True)
+deployment_app = typer.Typer(cls=SortedGroup, help="Manage dedicated deployments", no_args_is_help=True)
 
 
 # ---------------------------------------------------------------------------

roboflow/cli/handlers/folder.py

@@ -6,9 +6,9 @@
 
 import typer
 
-from roboflow.cli._compat import ctx_to_args
+from roboflow.cli._compat import SortedGroup, ctx_to_args
 
-folder_app = typer.Typer(help="Manage workspace folders", no_args_is_help=True)
+folder_app = typer.Typer(cls=SortedGroup, help="Manage workspace folders", no_args_is_help=True)
 
 
 @folder_app.command("list")

roboflow/cli/handlers/image.py

@@ -6,9 +6,9 @@
 
 import typer
 
-from roboflow.cli._compat import ctx_to_args
+from roboflow.cli._compat import SortedGroup, ctx_to_args
 
-image_app = typer.Typer(help="Image management commands", no_args_is_help=True)
+image_app = typer.Typer(cls=SortedGroup, help="Image management commands", no_args_is_help=True)
 
 
 @image_app.command("upload")

roboflow/cli/handlers/model.py

@@ -6,9 +6,9 @@
 
 import typer
 
-from roboflow.cli._compat import ctx_to_args
+from roboflow.cli._compat import SortedGroup, ctx_to_args
 
-model_app = typer.Typer(help="Manage trained models", no_args_is_help=True)
+model_app = typer.Typer(cls=SortedGroup, help="Manage trained models", no_args_is_help=True)
 
 
 @model_app.command("list")