fix(cli): polish help output, error hints, consistency

- Hide login/whoami/upload/import aliases from --help (keep download visible)
- Commands fully alphabetized in help output
- Exit code 0 (not 2) when running roboflow with no args
- Translate raw API hints ('issuing a GET request') to CLI hints
  ('roboflow project list', 'roboflow workspace get')
- workspace get defaults to current workspace when no arg given
- Hide --install-completion/--show-completion (we have 'completion' subcommand)
- Add 'roboflow help' command as alias for --help

374 tests pass, all linting clean.

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

Author: yeldarby

roboflow/cli/__init__.py

@@ -25,7 +25,6 @@
         "Manage datasets, train models, run inference, and deploy "
         "workflows \u2014 from the command line or via structured JSON for AI agents."
     ),
-    no_args_is_help=True,
     pretty_exceptions_enable=False,  # We handle errors ourselves via output_error
     rich_markup_mode="rich",
     add_completion=False,  # We have our own 'completion' subcommand
@@ -68,13 +67,18 @@ def _root_callback(
         typer.Option("--version", help="Show package version and exit", callback=_version_callback, is_eager=True),
     ] = None,
 ) -> None:
-    """Roboflow CLI: computer vision at your fingertips."""
+    """Build and deploy computer vision models with Roboflow."""
     ctx.ensure_object(dict)
     ctx.obj["json"] = json_output
     ctx.obj["api_key"] = api_key
     ctx.obj["workspace"] = workspace
     ctx.obj["quiet"] = quiet
 
+    # Show help and exit 0 when no subcommand is given
+    if ctx.invoked_subcommand is None:
+        print(ctx.get_help())  # noqa: T201
+        raise typer.Exit(code=0)
+
 
 # ---------------------------------------------------------------------------
 # Register command groups (explicit imports — no auto-discovery needed)
@@ -98,32 +102,41 @@ def _root_callback(
 from roboflow.cli.handlers.workflow import workflow_app  # noqa: E402
 from roboflow.cli.handlers.workspace import workspace_app  # noqa: E402
 
-# Register command groups (alphabetical order)
+# Register ALL commands in alphabetical order for clean --help output
 app.add_typer(annotation_app, name="annotation")
 app.add_typer(auth_app, name="auth")
 app.add_typer(batch_app, name="batch")
 app.add_typer(completion_app, name="completion")
 app.add_typer(deployment_app, name="deployment")
+
+# "download" alias — registered here alphabetically (visible shorthand)
+from roboflow.cli.handlers._aliases import register_download_alias  # noqa: E402
+
+register_download_alias(app)
+
 app.add_typer(folder_app, name="folder")
 app.add_typer(image_app, name="image")
+
+# "infer" — top-level command, registered alphabetically
+infer_command(app)
+
 app.add_typer(model_app, name="model")
 app.add_typer(project_app, name="project")
+
+# "search" — top-level command, registered alphabetically
+search_command(app)
+
 app.add_typer(train_app, name="train")
 app.add_typer(universe_app, name="universe")
 app.add_typer(version_app, name="version")
 app.add_typer(video_app, name="video")
 app.add_typer(workflow_app, name="workflow")
 app.add_typer(workspace_app, name="workspace")
 
-# Top-level commands (not nested under a group)
-infer_command(app)
-search_command(app)
-
-# "roboflow download" — visible shorthand (common enough to show)
-# "roboflow help" — alias for --help
-from roboflow.cli.handlers._aliases import register_aliases  # noqa: E402
+# Hidden aliases (loaded last — still functional but not in --help)
+from roboflow.cli.handlers._aliases import register_hidden_aliases  # noqa: E402
 
-register_aliases(app)
+register_hidden_aliases(app)
 
 
 # "roboflow help" command

roboflow/cli/_output.py

@@ -45,6 +45,22 @@ def output(args: Any, data: Any, text: Optional[str] = None) -> None:
     ("over_quota", "Your workspace has exceeded its quota. Visit https://roboflow.com/pricing to upgrade."),
 ]
 
+# Patterns to translate raw API hints into CLI-friendly hints
+_API_HINT_REPLACEMENTS: list[tuple[str, str]] = [
+    (
+        "You can see your active workspace by issuing a GET request to / with your api_key",
+        "Check available resources with 'roboflow project list' or 'roboflow workspace get'.",
+    ),
+    (
+        "You can find the API docs at https://docs.roboflow.com",
+        "Run the command with --help for usage information.",
+    ),
+    (
+        "You can see your available workspaces by issuing a GET request to /workspaces",
+        "List workspaces with 'roboflow workspace list'.",
+    ),
+]
+
 
 def _detect_plan_hint(message: str) -> Optional[str]:
     """Detect plan/billing-related errors and return an appropriate upgrade hint."""
@@ -55,6 +71,21 @@ def _detect_plan_hint(message: str) -> Optional[str]:
     return None
 
 
+def _translate_api_hints(message: str) -> str:
+    """Replace raw API hints with CLI-friendly equivalents."""
+    for api_hint, cli_hint in _API_HINT_REPLACEMENTS:
+        message = message.replace(api_hint, cli_hint)
+    # Generic fallback: strip any remaining "issuing a GET/POST request" phrasing
+    import re
+
+    message = re.sub(
+        r"You can [^.]*(?:GET|POST|PUT|DELETE) request[^.]*\.",
+        "Run the command with --help for usage information.",
+        message,
+    )
+    return message
+
+
 def _sanitize_credentials(text: str) -> str:
     """Strip API keys from URLs and other sensitive patterns in error messages."""
     import re
@@ -70,7 +101,7 @@ def _parse_error_message(raw: str) -> tuple[Optional[dict[str, Any]], str]:
     otherwise ``None``.  The *human_readable_message* drills into nested
     ``error.message`` structures so the text-mode output is clean.
     """
-    text = _sanitize_credentials(raw.strip())
+    text = _translate_api_hints(_sanitize_credentials(raw.strip()))
     # Strip status-code prefix like "404: {...}"
     colon_idx = text.find(": {")
     if 0 < colon_idx < 5:
@@ -81,9 +112,12 @@ def _parse_error_message(raw: str) -> tuple[Optional[dict[str, Any]], str]:
             err = parsed.get("error", parsed)
             if isinstance(err, dict):
                 human = str(err.get("message") or err.get("hint") or err)
+                # Translate API hints in the parsed dict too
+                if "hint" in err and isinstance(err["hint"], str):
+                    err["hint"] = _translate_api_hints(err["hint"])
             else:
                 human = str(err)
-            return parsed, human
+            return parsed, _translate_api_hints(human)
     except (json.JSONDecodeError, TypeError, ValueError):
         pass
     return None, text  # Return sanitized text, not the original raw

roboflow/cli/handlers/_aliases.py

@@ -1,10 +1,10 @@
 """Top-level backwards-compatibility aliases.
 
-Registers convenience commands at the root level (``roboflow login``,
-``roboflow upload``, etc.) that delegate to the canonical noun-verb handlers.
+Split into three registration functions called at different points in
+``__init__.py`` to control help ordering:
 
-This module is loaded *after* all other handlers so that it can import
-their handler functions.
+- ``register_download_alias(app)`` — visible ``download`` command (alphabetical slot)
+- ``register_hidden_aliases(app)`` — all hidden aliases (loaded last)
 """
 
 from __future__ import annotations
@@ -16,10 +16,27 @@
 from roboflow.cli._compat import ctx_to_args
 
 
-def register_aliases(app: typer.Typer) -> None:
-    """Register top-level aliases for common commands."""
+def register_download_alias(app: typer.Typer) -> None:
+    """Register the visible ``download`` shorthand at its alphabetical position."""
 
-    # --- roboflow login (hidden alias for auth login) ---
+    @app.command("download")
+    def download_alias(
+        ctx: typer.Context,
+        url_or_id: Annotated[
+            str, typer.Argument(metavar="datasetUrl", help="Dataset URL (e.g. workspace/project/version)")
+        ],
+        format: Annotated[str, typer.Option("-f", "--format", help="Export format")] = "voc",
+        location: Annotated[Optional[str], typer.Option("-l", "--location", help="Download location")] = None,
+    ) -> None:
+        """Download a dataset version (shorthand for 'version download')."""
+        from roboflow.cli.handlers.version import _download
+
+        args = ctx_to_args(ctx, url_or_id=url_or_id, format=format, location=location)
+        _download(args)
+
+
+def register_hidden_aliases(app: typer.Typer) -> None:
+    """Register all hidden backwards-compat aliases (not shown in --help)."""
 
     @app.command("login", hidden=True)
     def login_alias(
@@ -35,8 +52,6 @@ def login_alias(
         args = ctx_to_args(ctx, login_api_key=login_api_key, force=force)
         _login(args)
 
-    # --- roboflow whoami (hidden alias for auth status) ---
-
     @app.command("whoami", hidden=True)
     def whoami_alias(ctx: typer.Context) -> None:
         """Show current user (alias for 'auth status')."""
@@ -45,21 +60,19 @@ def whoami_alias(ctx: typer.Context) -> None:
         args = ctx_to_args(ctx)
         _status(args)
 
-    # --- roboflow upload (hidden alias for image upload) ---
-
     @app.command("upload", hidden=True)
     def upload_alias(
         ctx: typer.Context,
         path: Annotated[str, typer.Argument(help="Path to image file or directory")],
         project: Annotated[str, typer.Option("-p", "--project", help="Project ID")],
-        annotation: Annotated[Optional[str], typer.Option("-a", "--annotation", help="Path to annotation file")] = None,
-        labelmap: Annotated[Optional[str], typer.Option("-m", "--labelmap", help="Path to labelmap file")] = None,
+        annotation: Annotated[Optional[str], typer.Option("-a", "--annotation", help="Annotation file")] = None,
+        labelmap: Annotated[Optional[str], typer.Option("-m", "--labelmap", help="Labelmap file")] = None,
         split: Annotated[str, typer.Option("-s", "--split", help="Split (train/valid/test)")] = "train",
         num_retries: Annotated[int, typer.Option("-r", "--retries", help="Retry count")] = 0,
         batch: Annotated[Optional[str], typer.Option("-b", "--batch", help="Batch name")] = None,
-        tag_names: Annotated[Optional[str], typer.Option("-t", "--tag", help="Comma-separated tag names")] = None,
-        metadata: Annotated[Optional[str], typer.Option("-M", "--metadata", help="JSON metadata string")] = None,
-        concurrency: Annotated[int, typer.Option("-c", "--concurrency", help="Upload concurrency")] = 10,
+        tag_names: Annotated[Optional[str], typer.Option("-t", "--tag", help="Tag names")] = None,
+        metadata: Annotated[Optional[str], typer.Option("-M", "--metadata", help="JSON metadata")] = None,
+        concurrency: Annotated[int, typer.Option("-c", "--concurrency", help="Concurrency")] = 10,
         is_prediction: Annotated[bool, typer.Option("--is-prediction", help="Mark as prediction")] = False,
     ) -> None:
         """Upload images to a project (alias for 'image upload')."""
@@ -81,59 +94,33 @@ def upload_alias(
         )
         _handle_upload(args)
 
-    # --- roboflow import (hidden alias for image upload with directory) ---
-
     @app.command("import", hidden=True)
     def import_alias(
         ctx: typer.Context,
         path: Annotated[str, typer.Argument(metavar="folder", help="Path to dataset folder")],
         project: Annotated[str, typer.Option("-p", "--project", help="Project ID")],
-        concurrency: Annotated[int, typer.Option("-c", "--concurrency", help="Upload concurrency")] = 10,
+        concurrency: Annotated[int, typer.Option("-c", "--concurrency", help="Concurrency")] = 10,
         batch: Annotated[Optional[str], typer.Option("-n", "--batch-name", help="Batch name")] = None,
         num_retries: Annotated[int, typer.Option("-r", "--retries", help="Retry count")] = 0,
     ) -> None:
         """Import dataset from folder (alias for 'image upload')."""
         from roboflow.cli.handlers.image import _handle_upload
 
         args = ctx_to_args(
-            ctx,
-            path=path,
-            project=project,
-            concurrency=concurrency,
-            batch=batch,
-            num_retries=num_retries,
+            ctx, path=path, project=project, concurrency=concurrency, batch=batch, num_retries=num_retries
         )
         _handle_upload(args)
 
-    # --- roboflow download (visible alias for version download) ---
-
-    @app.command("download")
-    def download_alias(
-        ctx: typer.Context,
-        url_or_id: Annotated[
-            str, typer.Argument(metavar="datasetUrl", help="Dataset URL (e.g. workspace/project/version)")
-        ],
-        format: Annotated[str, typer.Option("-f", "--format", help="Export format")] = "voc",
-        location: Annotated[Optional[str], typer.Option("-l", "--location", help="Download location")] = None,
-    ) -> None:
-        """Download a dataset version (alias for 'version download')."""
-        from roboflow.cli.handlers.version import _download
-
-        args = ctx_to_args(ctx, url_or_id=url_or_id, format=format, location=location)
-        _download(args)
-
-    # --- roboflow search-export (hidden alias for search --export) ---
-
     @app.command("search-export", hidden=True)
     def search_export_alias(
         ctx: typer.Context,
-        query: Annotated[str, typer.Argument(help="Search query (e.g. 'tag:annotate' or '*')")],
-        format: Annotated[str, typer.Option("-f", help="Annotation format")] = "coco",
-        location: Annotated[Optional[str], typer.Option("-l", help="Local directory for export")] = None,
-        dataset: Annotated[Optional[str], typer.Option("-d", help="Limit to specific dataset")] = None,
-        annotation_group: Annotated[Optional[str], typer.Option("-g", help="Limit to annotation group")] = None,
+        query: Annotated[str, typer.Argument(help="Search query")],
+        format: Annotated[str, typer.Option("-f", help="Format")] = "coco",
+        location: Annotated[Optional[str], typer.Option("-l", help="Export location")] = None,
+        dataset: Annotated[Optional[str], typer.Option("-d", help="Limit to dataset")] = None,
+        annotation_group: Annotated[Optional[str], typer.Option("-g", help="Annotation group")] = None,
         name: Annotated[Optional[str], typer.Option("-n", help="Export name")] = None,
-        no_extract: Annotated[bool, typer.Option("--no-extract", help="Keep zip, skip extraction")] = False,
+        no_extract: Annotated[bool, typer.Option("--no-extract", help="Keep zip")] = False,
     ) -> None:
         """Export search results as a dataset."""
         from roboflow.cli.handlers.search import _search
@@ -151,16 +138,14 @@ def search_export_alias(
         )
         _search(args)
 
-    # --- roboflow upload_model (hidden alias for model upload) ---
-
     @app.command("upload_model", hidden=True)
     def upload_model_alias(
         ctx: typer.Context,
         project: Annotated[Optional[list[str]], typer.Option("-p", help="Project ID (repeatable)")] = None,
-        version_number: Annotated[Optional[int], typer.Option("-v", help="Version number")] = None,
+        version_number: Annotated[Optional[int], typer.Option("-v", help="Version")] = None,
         model_type: Annotated[Optional[str], typer.Option("-t", help="Model type")] = None,
-        model_path: Annotated[Optional[str], typer.Option("-m", help="Model file path")] = None,
-        filename: Annotated[str, typer.Option("-f", help="Model filename")] = "weights/best.pt",
+        model_path: Annotated[Optional[str], typer.Option("-m", help="Model path")] = None,
+        filename: Annotated[str, typer.Option("-f", help="Filename")] = "weights/best.pt",
         model_name: Annotated[Optional[str], typer.Option("-n", help="Model name")] = None,
     ) -> None:
         """Upload a model (hidden legacy alias)."""
@@ -177,49 +162,34 @@ def upload_model_alias(
         )
         _upload_model(args)
 
-    # --- roboflow get_workspace_info (hidden alias, preserved) ---
-
     @app.command("get_workspace_info", hidden=True)
     def get_workspace_info_alias(
         ctx: typer.Context,
         project: Annotated[Optional[str], typer.Option("-p", help="Project ID")] = None,
-        version_number: Annotated[Optional[int], typer.Option("-v", help="Version number")] = None,
+        version_number: Annotated[Optional[int], typer.Option("-v", help="Version")] = None,
     ) -> None:
         """Get workspace info (hidden legacy alias)."""
-        args = ctx_to_args(ctx, project=project, version_number=version_number)
-        _get_workspace_info_compat(args)
+        import roboflow as rf_mod
 
-    # --- roboflow run_video_inference_api (hidden alias for video infer) ---
+        args = ctx_to_args(ctx, project=project, version_number=version_number)
+        rf_obj = rf_mod.Roboflow(args.api_key)
+        workspace = rf_obj.workspace()
+        print("workspace", workspace)  # noqa: T201
+        proj = workspace.project(args.project)
+        print("project", proj)  # noqa: T201
+        ver = proj.version(args.version_number)
+        print("version", ver)  # noqa: T201
 
     @app.command("run_video_inference_api", hidden=True)
     def run_video_inference_api_alias(
         ctx: typer.Context,
         project: Annotated[Optional[str], typer.Option("-p", help="Project ID")] = None,
-        version_number: Annotated[Optional[int], typer.Option("-v", help="Version number")] = None,
-        video_file: Annotated[Optional[str], typer.Option("-f", help="Video file path")] = None,
+        version_number: Annotated[Optional[int], typer.Option("-v", help="Version")] = None,
+        video_file: Annotated[Optional[str], typer.Option("-f", help="Video file")] = None,
         fps: Annotated[int, typer.Option("-fps", help="FPS")] = 5,
     ) -> None:
         """Run video inference (hidden legacy alias)."""
         from roboflow.cli.handlers.video import _video_infer
 
-        args = ctx_to_args(
-            ctx,
-            project=project,
-            version_number=version_number,
-            video_file=video_file,
-            fps=fps,
-        )
+        args = ctx_to_args(ctx, project=project, version_number=version_number, video_file=video_file, fps=fps)
         _video_infer(args)
-
-
-def _get_workspace_info_compat(args) -> None:  # noqa: ANN001
-    """Backwards-compat handler for the old get_workspace_info command."""
-    import roboflow
-
-    rf = roboflow.Roboflow(args.api_key)
-    workspace = rf.workspace()
-    print("workspace", workspace)
-    project = workspace.project(args.project)
-    print("project", project)
-    version = project.version(args.version_number)
-    print("version", version)