# API and CLI Reference

This is the single entry point for operators and integrators who need:
- API contracts (OpenAPI, schemas, samples)
- CLI command guides and automation-friendly outputs
- Cross-cutting conventions (auth, tenancy, errors, determinism, offline posture)

Detailed references live under `docs/api/` and `docs/modules/cli/`.

## Quick links

| Goal | Open this |
| --- | --- |
| API conventions (headers, pagination, errors) | `docs/api/overview.md` |
| API versioning policy | `docs/api/versioning.md` |
| Gateway tenancy header policy | `docs/api/gateway/tenant-auth.md` |
| Gateway header hardening rules | `docs-archived/modules/gateway/identity-header-policy.md` |
| Console workspaces (findings/VEX views) | `docs/api/console/workspaces.md` |
| Console search and downloads | `docs/api/console/search-downloads.md` |
| Exceptions API entry point | `docs/api/exceptions.md` |
| Download aggregated OpenAPI via CLI | `docs/modules/cli/guides/commands/api.md` |
| CLI command reference (by command group) | `docs/modules/cli/guides/commands/` |
| CLI authentication and tokens | `docs/modules/cli/guides/commands/auth.md` |
| CLI Concelier job triggers (`db`) | `docs/modules/cli/guides/commands/db.md`, `docs/CONCELIER_CLI_QUICKSTART.md` |
| CLI offline/air-gap workflows | `docs/modules/cli/guides/commands/offline.md`, `docs/OFFLINE_KIT.md` |
| CLI reachability workflow | `docs/modules/cli/guides/commands/reachability.md` |
| CLI vulnerability workflow | `docs/modules/cli/guides/commands/vuln.md` |
| Vuln Explorer OpenAPI (v1) | `docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml` |
| Graph Gateway API (draft) | `docs/api/graph.md`, `docs/api/graph-gateway-spec-draft.yaml` |

## Where the API contracts live

StellaOps treats the OpenAPI documents and JSON schemas as the source of truth for HTTP shapes.

- Aggregation/discovery: `docs/api/openapi-discovery.md`
- Gateway-proxied reference docs + samples: `docs/api/gateway/`
- Service-specific OpenAPI (selected):
  - `docs/modules/vuln-explorer/openapi/vuln-explorer.v1.yaml`
  - `docs/api/notify-openapi.yaml`
  - `docs/api/taskrunner-openapi.yaml`
  - `docs/api/proofs-openapi.yaml`
  - `docs/api/vexlens-openapi.yaml`
- API samples and fixtures (deterministic): `docs/api/**/samples/`

If you are building an SDK or want a single document for tooling, prefer the CLI OpenAPI download flow:
- `stella api spec list`
- `stella api spec download --output ./openapi.yaml --format openapi-yaml`

See: `docs/modules/cli/guides/commands/api.md`.

## Where the CLI docs live

The `stella` CLI is documented as:
- High-level module docs: `docs/modules/cli/README.md`, `docs/modules/cli/architecture.md`
- Command guides: `docs/modules/cli/guides/commands/` (one file per command group)

CLI docs are written to match repo reality; avoid copying raw endpoint paths into the CLI guides unless they are backed by OpenAPI and tests.

## Cross-cutting conventions (high-level)

For the detailed contract, see `docs/api/overview.md`. The stable rules to keep in mind:

- Auth: bearer tokens are the baseline; sender-constrained modes (DPoP/mTLS) are deployment-profile dependent.
- Tenancy: every tenant-scoped request must carry an explicit tenant context (see `docs/api/gateway/tenant-auth.md`).
- Determinism: stable ordering, stable ids, UTC ISO-8601 timestamps, and canonical hashing where applicable.
- Streaming: some endpoints use NDJSON (`application/x-ndjson`) for deterministic, resumable tile/record streams.
- Offline-first: workflows must remain runnable in air-gapped mode using Offline Kit bundles and locally verifiable signatures.

## stella system migrations-run / migrations-status / migrations-verify

Database migration command group for SQL migrations managed by the shared PostgreSQL migration tooling.

### Synopsis

```bash
stella system migrations-status [--module <name>|all] [--connection <connection-string>]
stella system migrations-verify [--module <name>|all] [--connection <connection-string>]
stella system migrations-run [--module <name>|all] [--category <startup|release|seed|data>] [--dry-run] [--force]
```

### Options

| Option | Description |
| --- | --- |
| `--module` | Module name filter (`AirGap`, `Authority`, `Concelier`, `Excititor`, `Notify`, `Platform`, `Policy`, `Scanner`, `Scheduler`, `TimelineIndexer`, `all`). |
| `--category` | Migration category: `startup`, `release`, `seed`, `data`. |
| `--dry-run` | Preview migrations without executing SQL. |
| `--force` | Required to execute `release` category migrations. |
| `--connection` | Override PostgreSQL connection string for command execution. |
| `--timeout` | Timeout in seconds per migration command execution. |

### Examples

```bash
# Status across currently registered modules
stella system migrations-status --module all

# Checksum validation
stella system migrations-verify --module all

# Preview release migrations
stella system migrations-run --module all --category release --dry-run

# Execute release migrations
stella system migrations-run --module all --category release --force
```

### Current Coverage Notes

- CLI module coverage is currently defined in `src/Platform/__Libraries/StellaOps.Platform.Database/MigrationModuleRegistry.cs`.
- CLI module coverage is auto-discovered from one migration plug-in per web service (`IMigrationModulePlugin`).
- A service plug-in may flatten multiple migration sources into one service module descriptor (for example Scanner storage + triage sources).
- On empty migration history, CLI/API execution paths run one synthesized per-service consolidated migration (`100_consolidated_<service>.sql`) and then backfill legacy per-file history rows for compatibility with future incremental updates.
- If consolidated history exists but legacy backfill is partial, CLI/API paths automatically backfill missing legacy rows before source-set execution.
- This is a one-per-service bootstrap execution mode, not a permanent single-row migration history model.
- Registry ownership is platform-level so the same module catalog is reused by CLI and Platform migration admin APIs.
- Current registry coverage includes: `AirGap`, `Authority`, `Concelier`, `Excititor`, `Notify`, `Platform`, `Policy`, `Scanner`, `Scheduler`, `TimelineIndexer`.
- Not all migration folders in the repository are currently wired to runtime execution.
- Use `docs/db/MIGRATION_INVENTORY.md` for the current full matrix of migration locations, counts, and runner entrypoints.
- Consolidation target policy and cutover waves are defined in `docs/db/MIGRATION_CONSOLIDATION_PLAN.md`.
- For upgradeable on-prem operations, this command group is the canonical release-migration entrypoint.

### Platform Migration Admin API (UI / backend orchestration)

UI-driven migration operations must execute through Platform WebService (server-side only, no browser-direct PostgreSQL access).

- Base route: `/api/v1/admin/migrations`
- Authorization: `platform.setup.admin` (`PlatformPolicies.SetupAdmin`)
- Backing registry: `src/Platform/__Libraries/StellaOps.Platform.Database/MigrationModuleRegistry.cs`
- Endpoint implementation: `src/Platform/StellaOps.Platform.WebService/Endpoints/MigrationAdminEndpoints.cs`

API operations:

- `GET /api/v1/admin/migrations/modules`
- `GET /api/v1/admin/migrations/status?module=<name|all>`
- `GET /api/v1/admin/migrations/verify?module=<name|all>`
- `POST /api/v1/admin/migrations/run`
  - body: `{"module":"all","category":"release","dryRun":true,"force":false,"timeoutSeconds":300}`

Release safety guard:

- `category=release` requires either `dryRun=true` or `force=true`.

### Related Commands

```bash
# Seed demo datasets (seed migrations)
stella admin seed-demo --dry-run
stella admin seed-demo --confirm
```

## stella scan diff

Compare ELF binaries between two container images using section hashes.

### Synopsis

```bash
stella scan diff --base <image-ref> --target <image-ref> [options]
```

### Options

| Option | Description |
| --- | --- |
| `--base`, `-b` | Base image reference (tag or digest). |
| `--target`, `-t` | Target image reference (tag or digest). |
| `--mode`, `-m` | Analysis mode: `elf`, `pe`, `auto` (default: `auto`, currently uses ELF). |
| `--emit-dsse`, `-d` | Directory for DSSE attestation output. |
| `--signing-key` | Path to ECDSA private key (PEM) for DSSE signing. |
| `--format`, `-f` | Output format: `table`, `json`, `summary` (default: `table`). |
| `--platform`, `-p` | Platform filter (e.g., `linux/amd64`). |
| `--include-unchanged` | Include unchanged binaries in output. |
| `--sections` | Sections to analyze (comma-separated or repeatable). |
| `--registry-auth` | Path to Docker config for registry authentication. |
| `--timeout` | Timeout in seconds (default: 300). |
| `--verbose`, `-v` | Enable verbose output. |

Note: `--emit-dsse` requires `--signing-key` to sign the DSSE envelope.

### Examples

```bash
# Basic comparison
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1

# DSSE output with signing key
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 \
  --mode=elf --emit-dsse=./attestations --signing-key=./keys/binarydiff.pem

# JSON output for automation
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 --format=json > diff.json

# Specific platform
stella scan diff --base myapp:1.0.0 --target myapp:1.0.1 --platform=linux/amd64
```

### Output

DSSE output produces two files per platform:

```
attestations/
  linux-amd64-binarydiff.dsse.json
  linux-amd64-binarydiff.payload.json
```

See also: `docs/modules/scanner/binary-diff-attestation.md`.

## stella guard run

Run AI code guard checks on a change set (planned).

### Synopsis

```bash
stella guard run --policy <path> [options]
```

### Options

| Option | Description |
| --- | --- |
| `--policy` | Path to `.stellaops.yml` policy file. |
| `--format` | Output format: `json`, `sarif`, `gitlab`. |
| `--out` | Write output to file. |

### Examples

```bash
stella guard run --policy .stellaops.yml --format sarif --out guard.sarif
```

## stella image inspect

Inspect OCI image manifests and layers.

### Synopsis

```bash
stella image inspect <reference> [options]
```

### Options

| Option | Description |
| --- | --- |
| `--resolve-index`, `-r` | Resolve multi-arch index to platform manifests (default: true). |
| `--print-layers`, `-l` | Include layer details in output (default: true). |
| `--platform`, `-p` | Platform filter (e.g., `linux/amd64`). |
| `--output`, `-o` | Output format: `table`, `json` (default: `table`). |
| `--timeout` | Timeout in seconds (default: 60). |
| `--verbose`, `-v` | Enable verbose output. |

### Examples

```bash
# Basic inspection
stella image inspect nginx:latest

# JSON output
stella image inspect nginx:latest --output json

# Filter to a single platform
stella image inspect nginx:latest --platform linux/amd64

# Local registry over HTTP
stella image inspect http://localhost:5000/myapp:1.0.0
```

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Image not found |
| `2` | Error (auth, network, invalid input, timeout) |

## stella setup

Interactive setup wizard for configuring StellaOps components.

### Synopsis

```bash
stella setup [options]
stella setup --step <step-id> [options]
```

### Options

| Option | Description |
| --- | --- |
| `--step`, `-s` | Run a specific setup step (e.g., `llm`, `notify`, `authority`). |
| `--non-interactive` | Run in non-interactive mode using config values. |
| `--dry-run` | Preview changes without applying them. |
| `--config`, `-c` | Path to YAML configuration file. |
| `--verbose`, `-v` | Enable verbose output. |

### Available Steps

| Step ID | Name | Required | Description |
| --- | --- | --- | --- |
| `authority` | Authentication Provider | Yes | Configure authentication (Standard/LDAP). |
| `users` | User Management | Yes | Create super user and additional users. |
| `database` | PostgreSQL Database | Yes | Configure database connection. |
| `cache` | Valkey/Redis Cache | Yes | Configure cache connection. |
| `vault` | Secrets Vault | No | Configure secrets management (Vault/AWS/Azure). |
| `settingsstore` | Settings Store | No | Configure settings backend (Consul/etcd). |
| `registry` | Container Registry | No | Configure registry authentication. |
| `telemetry` | OpenTelemetry | No | Configure observability. |
| `notify` | Notifications | No | Configure notification channels. |
| `llm` | AI/LLM Provider | No | Configure LLM for AdvisoryAI. |

### Examples

```bash
# Run full setup wizard
stella setup

# Configure LLM provider only
stella setup --step llm

# Preview database configuration
stella setup --step database --dry-run

# Non-interactive with config file
stella setup --step llm --non-interactive --config ./setup.yaml
```

See also: `docs/modules/advisory-ai/llm-setup-guide.md` for LLM configuration details.

## stella advise ask

Ask questions to the AdvisoryAI assistant.

### Synopsis

```bash
stella advise ask <query> [options]
```

### Options

| Option | Description |
| --- | --- |
| `--image`, `-i` | Container image reference to scope the query. |
| `--digest`, `-d` | Artifact digest to scope the query. |
| `--environment`, `-e` | Environment context (e.g., production, staging). |
| `--conversation-id`, `-c` | Conversation ID for follow-up queries. |
| `--no-action`, `-n` | Suppress proposed actions (read-only mode). |
| `--evidence` | Include evidence links and citations. |
| `--format`, `-f` | Output format: `table`, `json`, `markdown`. |
| `--output`, `-o` | Write output to file. |
| `--tenant` | Tenant context. |
| `--user` | User context. |
| `--verbose`, `-v` | Enable verbose output. |

### Prerequisites

An LLM provider must be configured. If not configured, the command will display:

```
Error: AI/LLM provider not configured.

AdvisoryAI features require an LLM provider to be configured.
Run 'stella setup --step llm' to configure an LLM provider.

Alternatively, set one of these environment variables:
  - OPENAI_API_KEY      for OpenAI
  - ANTHROPIC_API_KEY   for Claude (Anthropic)
  - GEMINI_API_KEY      for Google Gemini
  - GOOGLE_API_KEY      for Google Gemini

Or configure Ollama for local LLM inference.
```

### Examples

```bash
# Basic query
stella advise ask "What vulnerabilities affect CVE-2024-1234?"

# Scoped to an image
stella advise ask "Is this image safe for production?" --image myapp:1.0.0

# With evidence citations
stella advise ask "Explain the risk of log4j in this artifact" \
  --digest sha256:abc123... --evidence

# JSON output for automation
stella advise ask "List critical vulnerabilities" --format json > report.json
```

## stella advise chat-doctor

Check AdvisoryAI chat quota and configuration status.

### Synopsis

```bash
stella advise chat-doctor [options]
```

### Options

| Option | Description |
| --- | --- |
| `--format`, `-f` | Output format: `table`, `json`. |
| `--output`, `-o` | Write output to file. |
| `--tenant` | Tenant context. |
| `--user` | User context. |
| `--verbose`, `-v` | Enable verbose output. |

### Examples

```bash
# Check configuration status
stella advise chat-doctor

# JSON output
stella advise chat-doctor --format json
```

## stella advise chat-settings

Manage AdvisoryAI chat settings and quotas.

### Synopsis

```bash
stella advise chat-settings get [options]
stella advise chat-settings update [options]
stella advise chat-settings clear [options]
```

### Get Options

| Option | Description |
| --- | --- |
| `--scope`, `-s` | Settings scope: `effective`, `user`, `tenant`. |
| `--format`, `-f` | Output format: `table`, `json`. |

### Update Options

| Option | Description |
| --- | --- |
| `--scope`, `-s` | Settings scope: `user`, `tenant`. |
| `--requests-per-minute` | Set requests per minute quota. |
| `--requests-per-day` | Set requests per day quota. |
| `--tokens-per-day` | Set tokens per day quota. |
| `--tool-calls-per-day` | Set tool calls per day quota. |
| `--allow-all-tools` | Allow all tools (true/false). |
| `--allowed-tools` | Set allowed tools (comma-separated). |

### Examples

```bash
# View effective settings
stella advise chat-settings get

# View user-level settings
stella advise chat-settings get --scope user

# Update quotas
stella advise chat-settings update --requests-per-day 100

# Clear user overrides
stella advise chat-settings clear --scope user
```

## stella search

Search AdvisoryAI Knowledge Search (AKS) across docs, API operations, and Doctor checks.

### Synopsis

```bash
stella search "<query>" [options]
```

### Options

| Option | Description |
| --- | --- |
| `--type` | Result type filter: `docs`, `api`, `doctor` (repeatable or comma-separated). |
| `--product` | Product filter. |
| `--version` | Version filter. |
| `--service` | Service filter (especially for API operations). |
| `--tag` | Tag filter (repeatable or comma-separated). |
| `--k` | Top result count (`1..100`). |
| `--json` | Emit stable machine-readable payload. |
| `--verbose`, `-v` | Include debug scoring fields when available. |

### Examples

```bash
stella search "docker login fails with x509 unknown authority"
stella search "endpoint for agent registration token" --type api --json
stella search "OIDC readiness checks" --type doctor --k 20
```

## stella doctor suggest

Use AKS to suggest Doctor checks, docs, and API references for a symptom string.

### Synopsis

```bash
stella doctor suggest "<symptom-or-error>" [options]
```

### Options

| Option | Description |
| --- | --- |
| `--product` | Product filter. |
| `--version` | Version filter. |
| `--k` | Top result count (`1..100`). |
| `--json` | Emit stable machine-readable payload. |
| `--verbose`, `-v` | Include debug scoring fields when available. |

### Examples

```bash
stella doctor suggest "database unavailable and timeout expired"
stella doctor suggest "gateway returns 404 on known route" --json
```

## stella advisoryai index rebuild

### Local repo build and use of the Stella CLI

When working from this repository, do not assume `stella` is already installed on `PATH`.
Use one of these local workflows first:

```bash
# Run the CLI directly from source
dotnet run --project "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -- advisoryai index rebuild --json

# Publish a reusable local binary
dotnet publish "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -c Release -o ".artifacts/stella-cli"

# Windows
.artifacts/stella-cli/StellaOps.Cli.exe advisoryai index rebuild --json

# Linux/macOS
./.artifacts/stella-cli/StellaOps.Cli advisoryai index rebuild --json
```

Related docs:
- CLI quickstart: `docs/modules/cli/guides/quickstart.md`
- AdvisoryAI live test setup: `src/AdvisoryAI/__Tests/INFRASTRUCTURE.md`

Rebuild the AdvisoryAI deterministic knowledge index from local markdown, OpenAPI specs, and Doctor metadata.

### Synopsis

```bash
stella advisoryai index rebuild [--json] [--verbose]
```

### Examples

```bash
stella advisoryai index rebuild
stella advisoryai index rebuild --json
```

## stella advisoryai sources prepare

Generate deterministic AdvisoryAI Knowledge Search (AKS) source artifacts used by index rebuild.
Doctor controls output is enriched from configured seed plus locally discovered Doctor checks (when Doctor engine services are available), providing fallback metadata for AdvisoryAI ingestion.

Requirements:
- In a source checkout, do not assume `stella` is already installed on `PATH`; build or run it from source first.
- Set `STELLAOPS_BACKEND_URL` (or the equivalent CLI config file value) when the command needs live Doctor check discovery.

### Synopsis

```bash
stella advisoryai sources prepare [options]
```

### Options

| Option | Description |
| --- | --- |
| `--repo-root` | Repository root used to resolve source paths. |
| `--docs-allowlist` | JSON allow-list for markdown source folders/files. |
| `--docs-manifest-output` | Output path for resolved docs manifest JSON (with hashes). |
| `--openapi-output` | Output path for aggregated OpenAPI JSON artifact. |
| `--doctor-seed` | Input doctor seed JSON path. |
| `--doctor-controls-output` | Output path for doctor controls projection JSON (controls + fallback metadata). |
| `--overwrite` | Overwrite existing output files. |
| `--json` | Emit stable machine-readable summary. |

### Examples

```bash
export STELLAOPS_BACKEND_URL="http://127.0.0.1:10451"
stella advisoryai sources prepare --json
stella advisoryai sources prepare --repo-root . --openapi-output devops/compose/openapi_current.json --overwrite
```