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).
• 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