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