Merge branch 'main' into feat/change-default-urls-to-serverless

Author: yeldarby

.github/workflows/publish.yml

@@ -2,23 +2,20 @@ name: Publish WorkFlow
 
 on:
   release:
-    types: [created]
+    types: [published]
 
 jobs:
   build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: [3.8]
     steps:
       - name: 🛎️ Checkout
         uses: actions/checkout@v4
         with:
           ref: ${{ github.head_ref }}
-      - name: 🐍 Set up Python ${{ matrix.python-version }}
+      - name: 🐍 Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: '3.10'
       - name: 🦾 Install dependencies
         run: |
           python -m pip install --upgrade pip
@@ -31,6 +28,29 @@ jobs:
         run: |
           make publish -e PYPI_USERNAME=$PYPI_USERNAME -e PYPI_PASSWORD=$PYPI_PASSWORD -e PYPI_TEST_PASSWORD=$PYPI_TEST_PASSWORD
 
+  build-slim:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🛎️ Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: 🦾 Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+      - name: 🚀 Publish roboflow-slim to PyPi
+        env:
+          PYPI_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: |
+          make publish-slim -e PYPI_USERNAME=$PYPI_USERNAME -e PYPI_PASSWORD=$PYPI_PASSWORD
+
   deploy-docs:
     needs: build
     runs-on: ubuntu-latest
@@ -45,7 +65,7 @@ jobs:
       - name: 🐍 Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.8'
+          python-version: '3.10'
 
       - name: 📚 Install MkDocs and dependencies
         run: |

.github/workflows/test.yml

@@ -6,12 +6,15 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 jobs:
   build:
     strategy:
       matrix:
         os: ["ubuntu-latest", "windows-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     env:
       PYTHONUTF8: 1
@@ -35,3 +38,24 @@ jobs:
           make check_code_quality
       - name: 🧪 Run tests
         run: "python -m unittest"
+
+  test-slim:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🛎️ Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+      - name: 🐍 Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: 🦾 Install slim dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-slim.txt
+          pip install -e . --no-deps
+          pip install responses
+      - name: 🧪 Run slim-compatible tests
+        run: "python -m unittest tests.test_slim_compat tests.test_vision_events"

.pre-commit-config.yaml

@@ -6,7 +6,7 @@ ci:
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: check-added-large-files
       - id: check-case-conflict
@@ -24,14 +24,14 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/PyCQA/bandit
-    rev: 1.8.3
+    rev: 1.9.3
     hooks:
       - id: bandit
         args: ["-c", "pyproject.toml"]
         additional_dependencies: ["bandit[toml]"]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.12
+    rev: v0.15.2
     hooks:
       - id: ruff-format
       - id: ruff

CLAUDE.md

@@ -84,28 +84,54 @@ 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 built on [typer](https://typer.tiangolo.com/) (which uses Click under the hood). `roboflow/roboflowpy.py` is a backwards-compatibility shim that delegates to `roboflow.cli.main`.
+
+**Package structure:**
+- `__init__.py` — Root `typer.Typer()` app with global `@app.callback()` for `--json`, `--workspace`, `--api-key`, `--quiet`. Explicitly registers all handler apps via `app.add_typer()`.
+- `_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
+- `_compat.py` — `ctx_to_args(ctx, **kwargs)` bridge that converts `typer.Context` to the `SimpleNamespace` that output helpers expect
+- `_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, each exporting a `typer.Typer()` app. `_aliases.py` registers backwards-compat top-level commands via `register_aliases(app)`.
+
+**Adding a new command:**
+1. Create `roboflow/cli/handlers/mycommand.py`
+2. Create a module-level `mycommand_app = typer.Typer(help="...", no_args_is_help=True)`
+3. Add commands with `@mycommand_app.command("verb")` decorators
+4. Each command takes `ctx: typer.Context` + typed params, calls `ctx_to_args(ctx, **params)` to create args namespace
+5. Use `output()` for all output, `output_error()` for all errors
+6. Wrap SDK calls in `with suppress_sdk_output():` to prevent "loading..." noise
+7. Register in `roboflow/cli/__init__.py`: `app.add_typer(mycommand_app, name="mycommand")`
+8. Add tests using `typer.testing.CliRunner` 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 Explicit Registration**: Handler apps are explicitly imported and registered via `app.add_typer()` in `__init__.py` — clear dependency chain, no runtime discovery
+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`
+- **Python Version**: 3.10+
+- **Main Dependencies**: See `requirements.txt` (includes `typer>=0.12.0`)
+- **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
+- **Type Checking**: mypy configured for Python 3.10
 
 ## Important Notes