Move generated commands under cycode platform namespace

Address review feedback: top-level registration caused namespace collisions
with curated commands (scan, auth, status, report) and triggered an OpenAPI
spec fetch on every invocation, leaking warnings into unrelated commands
like `cycode status`.

Generated commands now live under a single `platform` group that lazy-loads
the spec only when the user enters it. `cycode scan`, `cycode status`, and
all other commands no longer touch the spec or surface API-related warnings.

Tag groups are labeled `[BETA]` to make the maturity level explicit.

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

Author: MaorDavidzon

README.md

@@ -21,7 +21,11 @@ This guide walks you through both installation and usage.
     2. [Available Options](#available-options)
     3. [MCP Tools](#mcp-tools)
     4. [Usage Examples](#usage-examples)
-5. [Scan Command](#scan-command)
+5. [Platform Command](#platform-command-beta)
+    1. [Discovering Commands](#discovering-commands)
+    2. [Examples](#platform-examples)
+    3. [Notes & Limitations](#platform-notes--limitations)
+6. [Scan Command](#scan-command)
     1. [Running a Scan](#running-a-scan)
         1. [Options](#options)
            1. [Severity Threshold](#severity-option)
@@ -605,6 +609,64 @@ This information can be helpful when:
 - Debugging transport-specific issues
 
 
+# Platform Command \[BETA\]
+
+> [!WARNING]
+> The `platform` command is in **beta**. Commands, arguments, and output formats are generated dynamically from the Cycode API spec and may change between releases without notice. Do not rely on them in production automation yet.
+
+The `cycode platform` command exposes the Cycode platform's read APIs as CLI commands. It groups endpoints by resource (e.g. `projects`, `violations`, `workflows`) and turns each endpoint's parameters into typed CLI arguments and `--option` flags.
+
+```bash
+cycode platform projects list --page-size 50
+cycode platform violations count
+cycode platform workflows view <workflow-id>
+```
+
+The OpenAPI spec is fetched from the Cycode API on first use and cached at `~/.cycode/openapi-spec.json` for 24 hours. Unrelated commands (`cycode scan`, `cycode status`, etc.) do not trigger a fetch.
+
+> [!NOTE]
+> You must be authenticated (`cycode auth` or `CYCODE_CLIENT_ID` / `CYCODE_CLIENT_SECRET` environment variables) for `cycode platform` to discover and run commands. Other Cycode CLI commands work without authentication.
+
+## Discovering Commands
+
+Because commands are generated from the spec, the source of truth for what's available is `--help`:
+
+```bash
+cycode platform --help                  # list all resource groups
+cycode platform projects --help         # list actions on a resource
+cycode platform projects list --help    # list options/arguments for an action
+```
+
+## Platform Examples
+
+```bash
+# List projects with pagination
+cycode platform projects list --page-size 25
+
+# View a single project by ID
+cycode platform projects view <project-id>
+
+# Count violations across the tenant
+cycode platform violations count
+
+# Filter using query parameters (see `--help` for what each endpoint supports)
+cycode platform violations list --severity CRITICAL
+```
+
+All output is JSON by default — pipe it through `jq` for ad-hoc filtering:
+
+```bash
+cycode platform projects list --page-size 100 | jq '.items[].name'
+```
+
+## Platform Notes & Limitations
+
+- **Read-only today.** Only `GET` endpoints are exposed in this beta.
+- **Spec-driven.** Adding a new endpoint to the API surfaces it automatically the next time the cache is refreshed.
+- **No bundled spec.** The first `cycode platform` invocation after install (or after the 24h cache expires) will perform a network fetch with a 3-second timeout; if it times out, it continues fetching in the background so the next run is fast.
+- **Override the cache TTL** with `CYCODE_SPEC_CACHE_TTL=<seconds>`.
+
+
 # Scan Command
 
 ## Running a Scan

cycode/cli/app.py

@@ -11,7 +11,7 @@
 
 from cycode import __version__
 from cycode.cli.apps import ai_guardrails, ai_remediation, auth, configure, ignore, report, report_import, scan, status
-from cycode.cli.apps.api import get_api_command_groups
+from cycode.cli.apps.api import get_platform_group
 
 if sys.version_info >= (3, 10):
     from cycode.cli.apps import mcp
@@ -58,30 +58,26 @@
 if sys.version_info >= (3, 10):
     app.add_typer(mcp.app)
 
-# Register API v4 command groups (dynamically built from OpenAPI spec).
-# Typer resolves to a Click group on invocation. We store the API groups
-# and inject them via a registered_callback that runs at group resolution time.
-_api_groups_to_register = get_api_command_groups()
-
-
-# Monkey-patch typer.main.get_group to inject API Click groups into the Typer CLI.
-# This is necessary because Typer doesn't support adding native Click groups directly.
-# Typer creates a new Click group on each get_group() call, so we intercept that call
-# and add our API groups to the result. The `app_typer is app` guard ensures we only
-# modify our own app, not other Typer apps in the process.
+# Register the `platform` command group (dynamically built from the OpenAPI spec).
+# The group itself is constructed cheaply at import time; the spec is only fetched
+# when the user actually invokes `cycode platform ...`. Unrelated commands like
+# `cycode scan` and `cycode status` never trigger a spec fetch.
+#
+# Typer doesn't support adding native Click groups directly, so we monkey-patch
+# typer.main.get_group to inject our `platform` group into the resolved Click group.
+# The `app_typer is app` guard ensures we only modify our own app.
+_platform_group = get_platform_group()
 _original_get_group = typer.main.get_group
 
 
-def _get_group_with_api(app_typer: typer.Typer) -> click.Group:
+def _get_group_with_platform(app_typer: typer.Typer) -> click.Group:
     group = _original_get_group(app_typer)
-    if app_typer is app and _api_groups_to_register:
-        for api_group, api_name in _api_groups_to_register:
-            if api_name not in group.commands:
-                group.add_command(api_group, api_name)
+    if app_typer is app and _platform_group.name not in group.commands:
+        group.add_command(_platform_group, _platform_group.name)
     return group
 
 
-typer.main.get_group = _get_group_with_api
+typer.main.get_group = _get_group_with_platform
 
 
 def check_latest_version_on_close(ctx: typer.Context) -> None:

cycode/cli/apps/api/__init__.py

@@ -1,7 +1,8 @@
-"""Cycode API v4 CLI commands.
+"""Cycode platform API CLI commands.
 
 Dynamically builds CLI command groups from the Cycode API v4 OpenAPI spec.
-The spec is fetched from the API and cached locally for 24 hours.
+The spec is fetched lazily — only when the user invokes `cycode platform ...` —
+and cached locally for 24 hours.
 """
 
 from typing import Optional
@@ -10,21 +11,57 @@
 
 from cycode.logger import get_logger
 
-logger = get_logger('API')
+logger = get_logger('Platform')
 
+_PLATFORM_HELP = (
+    '[BETA] Access the Cycode platform.\n\n'
+    'Commands are generated dynamically from the Cycode API spec and may change '
+    'between releases. The spec is fetched on first use and cached for 24 hours.'
+)
 
-def get_api_command_groups(
-    client_id: Optional[str] = None,
-    client_secret: Optional[str] = None,
-) -> list[tuple[click.Group, str]]:
-    """Get API command groups built from the OpenAPI spec.
 
-    Returns empty list if the spec is not available (not authenticated, no cache).
+class PlatformGroup(click.Group):
+    """Lazy-loading Click group for `cycode platform` subcommands.
+
+    The OpenAPI spec is only fetched when the user actually invokes
+    `cycode platform ...` (or asks for its help). Unrelated commands like
+    `cycode scan` or `cycode status` never trigger a spec fetch.
     """
-    try:
-        from cycode.cli.apps.api.api_command import build_api_command_groups
 
-        return build_api_command_groups(client_id, client_secret)
-    except Exception as e:
-        logger.debug('Could not load API commands: %s', e)
-        return []
+    _loaded: bool = False
+
+    def _ensure_loaded(self, ctx: Optional[click.Context]) -> None:
+        if self._loaded:
+            return
+        self._loaded = True  # set first to avoid re-entrancy on errors
+
+        client_id = client_secret = None
+        if ctx is not None:
+            root = ctx.find_root()
+            if root.obj:
+                client_id = root.obj.get('client_id')
+                client_secret = root.obj.get('client_secret')
+
+        try:
+            from cycode.cli.apps.api.api_command import build_api_command_groups
+
+            for sub_group, name in build_api_command_groups(client_id, client_secret):
+                if name not in self.commands:
+                    self.add_command(sub_group, name)
+        except Exception as e:
+            logger.debug('Could not load platform commands: %s', e)
+            # Surface the error to the user only when they're inside `platform`
+            click.echo(f'Error loading Cycode platform commands: {e}', err=True)
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        self._ensure_loaded(ctx)
+        return super().list_commands(ctx)
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> Optional[click.Command]:
+        self._ensure_loaded(ctx)
+        return super().get_command(ctx, cmd_name)
+
+
+def get_platform_group() -> click.Group:
+    """Return the top-level `platform` Click group (lazy-loading)."""
+    return PlatformGroup(name='platform', help=_PLATFORM_HELP, no_args_is_help=True)

cycode/cli/apps/api/api_command.py

@@ -134,7 +134,7 @@ def build_api_command_groups(
     for tag, endpoints in groups.items():
         tag_name = _normalize_tag(tag)
 
-        group = click.Group(name=tag_name, help=f'[EXPERIMENT] Cycode API: {tag}')
+        group = click.Group(name=tag_name, help=f'[BETA] {tag}')
 
         # Compute common prefix from all GET (non-deprecated) endpoint paths in this tag
         get_endpoints = [ep for ep in endpoints if ep['method'] == 'get' and not ep.get('deprecated')]