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

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