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-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

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: AdvisoryAI, AirGap, Attestor, Authority, BinaryIndex, Concelier, Eventing, Evidence, EvidenceLocker, Excititor, ExportCenter, FindingsLedger, Graph, Integrations, IssuerDirectory, Notify, OpsMemory, PacksRegistry, Platform, PluginRegistry, Policy, ReachGraph, ReleaseOrchestrator, Remediation, Replay, RiskEngine, SbomLineage, Scanner, Scheduler, Signals, Signer, TimelineIndexer, Unknowns, Verdict, VexHub, VexLens, Workflow.
• 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

# Optional manual demo datasets (not part of default bootstrap)
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

Installation-scoped control-plane bootstrap for the running StellaOps platform.

Synopsis

stella setup [--config <path>] [--non-interactive]
stella setup run [options]
stella setup resume [--session <id>]
stella setup status [--session <id>] [--json]
stella setup reset [--step <step-id> | --all] [--force]
stella setup validate --config <path>

Options

Option	Description
--config, -c	Path to the YAML configuration file used to seed setup draft values.
--non-interactive, -y	Run without prompts.
--step, -s	run/reset only. Limit the operation to one supported control-plane step.
--dry-run	run only. Probe without applying.
--force, -f	run starts a fresh session; reset --all skips confirmation.
--session	resume/status only. Use an explicit session id.
--json	status only. Emit machine-readable session state with sanitized draftValues and retained-secret secretDrafts metadata.
--verbose, -v	Enable verbose output.

Available Steps

Step ID	Name	Required	Description
database	PostgreSQL Database	Yes	Configure database connection.
cache	Valkey/Redis Cache	Yes	Configure cache connection.
migrations	Database Migrations	Yes	Converge the required schema migrations.
admin	Admin Bootstrap	Yes	Ensure the bootstrap administrator exists.
crypto	Crypto Profile	Yes	Validate and apply the selected crypto profile.

Compatibility aliases still accepted:

• valkey -> cache
• authority -> admin
• users -> admin

Former setup targets such as vault, settingsstore, registry, scm, notify, telemetry, llm, sources, environments, and agents now return explicit handoff guidance to the authenticated onboarding surfaces.

Examples

# Run the installation bootstrap
stella setup run

# Probe only
stella setup run --step database --dry-run --config ./setup.yaml

# Resume and inspect status
stella setup resume
stella setup status --json

# Reset the installation session
stella setup reset --all --force

After stella setup, use the authenticated integration/onboarding surfaces instead of more setup steps:

stella config integrations bootstrap local
stella config integrations bootstrap local --include-gitlab
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry

# Production or customer-managed systems still use BYO-secret onboarding
stella config integrations secrets targets
stella config integrations secrets upsert-bundle \
  --bundle gitlab-server \
  --target <vault-integration-id> \
  --path gitlab/server \
  --entry access-token=glpat-...

Setup-session secret handling:

• Session reads never return plaintext secret values.
• Retained setup secrets surface only as secretDrafts metadata and are reused server-side during resume/apply.

stella config integrations bootstrap local

Bootstrap the Stella-owned local compose fixture catalog from the CLI.

Synopsis

stella config integrations bootstrap local [--include-gitlab] [--include-gitlab-registry] [--format table|json]

Options

Option	Description
--include-gitlab	Include the owned local GitLab Server and GitLab CI fixtures. The CLI mints and stages the local PAT into Vault automatically.
--include-gitlab-registry	Include the optional local GitLab container registry fixture. Requires the heavy GitLab compose profile with GITLAB_ENABLE_REGISTRY=true.
--format	Output format: table or json (default: table).
--verbose, -v	Enable verbose output.

Examples

# Default 13-entry local fixture catalog
stella config integrations bootstrap local

# Add GitLab Server and GitLab CI
stella config integrations bootstrap local --include-gitlab

# Add the optional GitLab registry and emit machine-readable results
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry --format json

Contract

• This command is for Stella-owned local compose fixtures only.
• Default mode creates or updates 13 deterministic local integrations and verifies both connector test and runtime health for each selected entry.
• --include-gitlab stages the owned local GitLab PAT through Secret Authority and binds the returned authref://vault/gitlab#access-token value to GitLab Server and GitLab CI.
• --include-gitlab-registry stages and binds authref://vault/gitlab#registry-basic for the optional local GitLab registry surface, which must be started with GITLAB_ENABLE_REGISTRY=true.
• Exit code 0 means every selected integration tested healthy and reported healthy runtime status. Exit code 1 means bootstrap or verification failed.
• For production or customer-managed systems, use stella config integrations secrets targets, stella config integrations secrets upsert-bundle, and explicit create or update operations with operator-provided credentials.

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.
Use the AdvisoryAI integration surfaces 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

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:

# Run the CLI directly from source
dotnet run --project "src/Cli/StellaOps.Cli/StellaOps.Cli.csproj" -- --help

# 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 --help

# Linux/macOS
./.artifacts/stella-cli/StellaOps.Cli --help

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.

Local source-checkout note:

• stella advisoryai index rebuild calls an authenticated backend endpoint.
• For the unauthenticated local live-search verification lane, use stella advisoryai sources prepare plus the direct HTTP rebuild calls documented in src/AdvisoryAI/__Tests/INFRASTRUCTURE.md.

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.

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

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

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