Merge pull request #445 from roboflow/apr-2026/cli-modernization

feat(cli): modularize CLI with noun-verb commands, --json output, and auto-discovery

Author: yeldarby

CLAUDE.md

@@ -84,26 +84,49 @@ The Roboflow Python SDK follows a hierarchical object model that mirrors the Rob
 - **rfapi** (`roboflow/adapters/rfapi.py`) - Low-level API communication
 - **deploymentapi** (`roboflow/adapters/deploymentapi.py`) - Model deployment operations
 
-### CLI Interface
-
-The `roboflow` command line tool (`roboflow/roboflowpy.py`) provides:
-- Authentication: `roboflow login`
-- Dataset operations: `roboflow download`, `roboflow upload`, `roboflow import`
-- Inference: `roboflow infer`
-- Project/workspace management: `roboflow project`, `roboflow workspace`
+### CLI Package (`roboflow/cli/`)
+
+The CLI is a modular package with auto-discovered handler modules. `roboflow/roboflowpy.py` is a backwards-compatibility shim that delegates to `roboflow.cli.main`.
+
+**Package structure:**
+- `__init__.py` — Root parser with global flags (`--json`, `--workspace`, `--api-key`, `--quiet`), auto-discovery via `pkgutil.iter_modules`, custom `_CleanHelpFormatter`, and `_reorder_argv` for flexible flag positioning
+- `_output.py` — `output(args, data, text)` for JSON/text output, `output_error(args, msg, hint, exit_code)` for structured errors, `suppress_sdk_output()` to silence SDK noise, `stub()` for unimplemented commands
+- `_table.py` — `format_table(rows, columns)` for columnar list output
+- `_resolver.py` — `resolve_resource(shorthand)` for parsing `project`, `ws/project`, `ws/project/3`
+- `handlers/` — One file per command group (auto-discovered). `_aliases.py` registers backwards-compat top-level commands (loaded last)
+
+**Adding a new command:**
+1. Create `roboflow/cli/handlers/mycommand.py`
+2. Export `register(subparsers)` — it will be auto-discovered
+3. Use lazy imports for heavy dependencies (inside handler functions, not at module top level)
+4. Use `output()` for all output, `output_error()` for all errors
+5. Wrap SDK calls in `with suppress_sdk_output():` to prevent "loading..." noise
+6. Add tests in `tests/cli/test_mycommand_handler.py`
+
+**Agent experience requirements for all CLI commands:**
+- Support `--json` for structured output (stable schema)
+- No interactive prompts when all required flags are provided
+- Structured error output: `{"error": {"message": "...", "hint": "..."}}` on stderr
+- Exit codes: 0 = success, 1 = error, 2 = auth error, 3 = not found
+- Actionable error messages: always tell the user what went wrong AND what to do
+
+**Documentation policy:** `CLI-COMMANDS.md` in this repo is a quickstart only. The full command reference lives in `roboflow-product-docs` (published to docs.roboflow.com). When adding commands, update both.
 
 ### Key Design Patterns
 
 1. **Hierarchical Access**: Always access objects through their parent (Workspace → Project → Version → Model)
 2. **API Key Flow**: API key is passed down through the object hierarchy
 3. **Format Flexibility**: Supports multiple dataset formats (YOLO, COCO, Pascal VOC, etc.)
 4. **Batch Operations**: Upload and download operations support concurrent processing
+5. **CLI Noun-Verb Pattern**: Commands follow `roboflow <noun> <verb>` (e.g. `roboflow project list`). Common operations have top-level aliases (`login`, `upload`, `download`)
+6. **CLI Auto-Discovery**: Handler modules in `roboflow/cli/handlers/` are loaded automatically — no registration list to maintain
+7. **Backwards Compatibility**: Legacy command names and flag signatures are preserved as hidden aliases
 
 ## Project Configuration
 
 - **Python Version**: 3.8+
 - **Main Dependencies**: See `requirements.txt`
-- **Entry Point**: `roboflow=roboflow.roboflowpy:main`
+- **Entry Point**: `roboflow=roboflow.roboflowpy:main` (shim delegates to `roboflow.cli.main`)
 - **Code Style**: Enforced by ruff with Google docstring convention
 - **Type Checking**: mypy configured for Python 3.8