git.stella-ops.org/docs/API_CLI_REFERENCE.md

# 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/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 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
```