spot-cli architecture¶

This document captures how the CLI is organised, how it talks to the api-gateway, and which assumptions it leans on. It is aimed at contributors changing CLI internals, not at operators using the tool.

Module layout¶

services/cli/
├── src/spot_cli/
│   ├── __init__.py            # __version__
│   ├── __main__.py            # python -m spot_cli entry point
│   ├── main.py                # Typer app + sub-app registration
│   ├── api_client.py          # Thin httpx2 wrapper, token refresh, error mapping
│   ├── config_paths.py        # Token-dir resolution
│   ├── output.py              # Coloured info / success / error / warn
│   ├── profiles.py            # Install profiles, generated secrets, the .env
│   └── commands/
│       ├── auth.py
│       ├── health.py
│       ├── version.py
│       ├── audit.py
│       ├── watch.py
│       ├── plugin.py
│       ├── profile.py
│       ├── workflow.py
│       ├── routing.py
│       ├── analyze.py
│       ├── config.py
│       ├── queues.py
│       └── benchmark/         # Benchmark suite (own subpackage)
└── tests/

There is no business logic in the CLI beyond argument parsing, authentication, HTTP calls, and rendering, the benchmark suite and the install profiles aside (below). Everything substantive -- plugin lifecycle, workflow validation, configuration parsing -- lives behind api-gateway endpoints. This is by design: the CLI must work against any deployment of the platform, including ones the operator cannot SSH into.

Communication contract¶

info, schema, enable, disable and token first find the plugin's section of spot.yaml in GET /api/v1/config/plugins; with a --kind that is not that section, they stop and name the plugin's kind, without reading its entry.

The RBAC column reflects the gateway's enforcement; if a token does not satisfy the role the gateway returns 403 and spot-cli surfaces that as Forbidden: your role lacks permission for <method> <path> and exits 1.

Token storage¶

Tokens live in two files under $SPOT_TOKEN_DIR (default ~/.config/spot-cli/):

~/.config/spot-cli/
├── token          # access_token (short-lived)
└── token-refresh  # refresh_token (long-lived, optional)

api_client.py reads them lazily, attaches them as Authorization: Bearer <token>, and on a 401 transparently:

1. Reads token-refresh.
2. POSTs { refresh_token } to /auth/refresh.
3. On success, replaces token with the new access token and retries the original request once.
4. On failure, deletes both files and bubbles the 401 up so the caller can re-run auth login.

Error mapping¶

api_client.request() is the single entry point for every gateway call. It maps the failure modes operators care about into human-friendly messages:

Every mapped path raises typer.Exit(1); unmapped exceptions still propagate to give a stack trace useful for bug reports. Three callers ask for an answer instead: with raise_unavailable, a 503 raises UnavailableError, for a caller that can do without the answer; with raise_not_found, a 404 raises NotFoundError, for a caller that names what was not found or asks whether something exists; with raise_unreachable, a gateway that cannot be reached or does not answer in time raises UnreachableError, for a caller that reads again, as watch does.

Rendering¶

Text that comes from outside SPOT, such as an email's subject, an analyzer's evidence or an image's labels, goes through output.plain() before a table shows it: Rich markup in it is not interpreted, and each control character becomes U+FFFD, so it cannot move the terminal's cursor or rewrite what is already shown.

A command that shows data fetches it, then calls output.emit with the format --output gave, the data and a function that prints it for a person. table calls that function, which prints what the command printed before --output; json and yaml print the data alone on standard output, in ASCII.

Profiles¶

profiles.py holds the install profiles (minimal, standard, full) as data, versioned with the images they install: each one's plugins, with their settings, whether they need the content consent and their memory; its workflow, built from spot-sdk-python's models; its compose profiles and .env settings; and what its host needs. The memory figures come from measurements on a test instance, each named next to its constant. The module also generates a new install's secrets (Python's secrets) and renders its .env from .env.example.

commands/profile.py exposes them. requirements and env read no gateway: the deployment wrapper's setup calls them before the stack runs. apply reads what the platform holds and changes only what is missing; it reads time.monotonic and time.sleep through the time module, as analyze submit --wait does, so tests replace both.

Benchmark subpackage¶

commands/benchmark/ is the command group with the most local logic. It owns:

• datasets.py -- registry of supported corpora and their formats.
• models.py -- Pydantic models for normalised emails (each an RFC 5322 message, base64 in the JSONL), run state, metrics.
• normalize.py -- Format-specific parsers (CSV, JSON, Maildir) that build each message, or keep it byte for byte (Maildir).
• run.py -- Submits batches, polls, persists results.
• report.py -- Computes metrics from run results, with the SDK's spot_sdk.testing.metrics as plugin test does, and saves them to metrics.json.
• compare.py -- Side-by-side comparison of two runs.

Datasets are intentionally not committed to this repo; they live in a separate dataset repository operators clone next to spot/. SPOT_DATASETS_DIR resolves the location.

Coverage¶

The CLI is held to 100% line coverage (--cov-fail-under=100). The genuinely unreachable async networking branches in benchmark/run.py are marked # pragma: no cover with a one-line justification next to each.

Why no shared library¶

A previous iteration extracted helpers into a cli-common library so they could be reused by hypothetical "operator scripts." That never materialised, so the abstraction was removed. The CLI is small enough that a flat layout under src/spot_cli/ reads better than a layered one. Add a shared module only when there's a concrete second consumer.