spot-cli user guide¶

spot-cli is the operator client for a deployed SPOT platform. It talks to the api-gateway over HTTP using the same OAuth2 password-grant flow as the web dashboard, and persists access tokens locally so each shell command does not require re-authenticating.

This guide walks through the everyday operator flow. If you have not put the spot-cli wrapper on your PATH yet, see the install guide -- it's a one-line symlink.

Authenticating¶

Before any other command works you need a token. spot-cli prompts interactively, or reads SPOT_USERNAME / SPOT_PASSWORD from the environment if you want to script it.

spot-cli auth login                                 # interactive prompt
SPOT_USERNAME=alice spot-cli auth login -p s3cret   # non-interactive
spot-cli auth whoami                                # who am I (and is the token still valid)?
spot-cli auth refresh                               # force a refresh round-trip
spot-cli auth logout                                # forget the cached tokens

Tokens land in ~/.config/spot-cli/ (or $SPOT_TOKEN_DIR). When the access token expires, spot-cli refreshes it automatically using the saved refresh token; you only see a re-prompt if the refresh itself fails.

Health and version¶

spot-cli health           # platform + plugin health rollup
spot-cli version          # CLI + platform versions

spot-cli health calls /api/v1/system/health on the gateway, which fans out to every platform service and every enabled plugin; the table shows which dependencies the gateway considers reachable. spot-cli version prints the CLI version, the gateway version, and each plugin's reported version side by side, which is the fastest way to confirm an upgrade landed.

Plugins¶

There is one plugin command group. Use --kind to scope it to a specific type (analyzer, context_provider, mail_retriever); leave it off to operate across all kinds.

spot-cli plugin list                          # all installed plugins
spot-cli plugin list --kind analyzer          # just analyzers
spot-cli plugin list --catalog --kind analyzer  # available in the catalog

spot-cli plugin info analyzer-nlp             # current settings + status
spot-cli plugin schema analyzer-nlp           # settings JSON Schema

spot-cli plugin install analyzer-nlp          # from the catalog
spot-cli plugin enable analyzer-nlp
spot-cli plugin disable analyzer-nlp
spot-cli plugin update analyzer-nlp \
    --setting threshold=0.85 \
    --setting model=distilbert-base
spot-cli plugin remove analyzer-nlp

install, remove, enable, disable, and update write to spot.yaml through the api-gateway; the orchestrator picks the change up on its next per-job re-read, so no service restart is required.

Workflows¶

Workflows describe how analyzers chain together. The CLI mirrors the api-gateway's CRUD endpoints:

spot-cli workflow list
spot-cli workflow get default-workflow
spot-cli workflow create -f workflows/strict.yaml
spot-cli workflow update strict --default
spot-cli workflow delete obsolete-workflow

The YAML file passed to create and update is validated server-side against the platform's Pydantic models. If validation fails the gateway returns 422 with a list of {path, message} pairs that spot-cli prints inline.

Submitting an analysis¶

spot-cli analyze submit email.json                 # from a JSON-encoded email
spot-cli analyze submit email.json --workflow strict
spot-cli analyze get <job_id>                      # one job's verdict
spot-cli analyze list                              # recent jobs

submit returns the job_id immediately. get calls /api/v1/analyze/{id} and renders verdict, threat level, confidence, and the per-stage analyzer results. list paginates through recent jobs (--limit, --offset).

Configuration¶

spot-cli config show                              # full live spot.yaml
spot-cli config show plugins.analyzers            # walk into a section
spot-cli config platform                          # platform settings table
spot-cli config validate spot.yaml
spot-cli config validate workflows/strict.yaml --kind workflows

show returns the active configuration as the gateway sees it, with secrets redacted. validate POSTs the YAML body to /api/v1/config/validate, which parses it through the same models the loader uses at startup; this is how you sanity-check a change before editing the file in place.

validate is read-only and never modifies the live spot.yaml.

Benchmarks¶

Benchmarks live in spot-cli because the corpora, normalisation, batching, and metric-comparison logic are part of the same versioned artefact. The corpora themselves live in a separate dataset repo that the benchmark commands fetch into a workspace under $SPOT_BENCHMARK_DIR.

spot-cli benchmark normalize -d phishing-corpus-2024
spot-cli benchmark run --workflow default-workflow --datasets phishing-corpus-2024
spot-cli benchmark report                        # most recent run
spot-cli benchmark report --baseline run-2026-04-01

run submits emails in batches through /api/v1/analyze, polls until each job completes, persists raw verdicts plus computed precision / recall / F1 metrics under $SPOT_BENCHMARK_DIR/runs/<run_id>/, and prints a summary. report re-renders metrics from disk and optionally diffs them against a baseline run so you can track accuracy over time.

Common environment variables¶

Variable	Purpose	Default
`SPOT_API_URL`	Base URL of the api-gateway	`http://api-gateway:8000`
`SPOT_TOKEN_DIR`	Where tokens are persisted	`~/.config/spot-cli/`
`SPOT_USERNAME`	Skip the interactive `Username` prompt	unset
`SPOT_PASSWORD`	Skip the interactive `Password` prompt	unset
`SPOT_DATASETS_DIR`	Directory of raw benchmark datasets	`./datasets`
`SPOT_BENCHMARK_DIR`	Workspace for normalised data, runs, reports	`./benchmarks`

Exit codes¶

Code	Meaning
0	Command succeeded.
1	Command failed (auth error, validation error, gateway 4xx/5xx, etc.).
2	Bad invocation (missing argument, unknown command). Typer-driven.

Troubleshooting¶

Cannot connect to http://api-gateway:8000 — set SPOT_API_URL to the gateway URL reachable from your shell. The default only works inside the compose network.
401 Unauthorized on every command — the access token expired and the refresh token was rejected. Run spot-cli auth login again.
Cannot find spot.yaml on config validate — the path is resolved relative to the current shell, not the container; pass an absolute path or run from the repo root.
spot-cli benchmark cannot find datasets — set SPOT_DATASETS_DIR to where you cloned the dataset repo.