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 system migrations-run / migrations-status / migrations-verify

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

Synopsis

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

# 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

# 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

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

# 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

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

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

stella image inspect

Inspect OCI image manifests and layers.

Synopsis

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

# 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

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

# 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

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

# 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

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

# 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

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

# 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

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

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

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

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

stella advisoryai index rebuild

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

Synopsis

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

Examples

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.

Synopsis

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

stella advisoryai sources prepare --json
stella advisoryai sources prepare --repo-root . --openapi-output devops/compose/openapi_current.json --overwrite