stella api — Command Guide

Audience: SDK authors, integration engineers, and CI authors who consume Stella Ops OpenAPI specifications. Scope: Listing and downloading service or aggregate OpenAPI specs, with ETag caching and checksum verification.

Overview

The stella api command group retrieves Stella Ops OpenAPI specifications — either the aggregate spec spanning all services or a single service’s spec. Downloads support conditional fetching via ETag and integrity verification via checksum, making them suitable for deterministic client-code generation in CI.

Commands

List API specifications

# List available API specifications
stella api spec list \
  [--tenant <id>] \
  [--json]

Options:

Flag	Description
`--tenant` / `-t`	Tenant context for the operation
`--json`	Output in JSON format

Output:

Aggregate API specification details (version, OpenAPI version, ETag, SHA-256)
Service-level specifications with version and format information

Download API specification

# Download API specification
stella api spec download \
  --output <path> \
  [--tenant <id>] \
  [--service <name>] \
  [--format openapi-json|openapi-yaml] \
  [--overwrite] \
  [--etag <etag>] \
  [--checksum <checksum>] \
  [--checksum-algorithm sha256|sha384|sha512] \
  [--json]

Options:

Flag	Description
`--output` / `-o`	Output path for the downloaded spec (file or directory) (required)
`--service` / `-s`	Service to download spec for (e.g., concelier, scanner, policy). Omit for aggregate spec
`--format` / `-f`	Output format: `openapi-json` (default) or `openapi-yaml`
`--overwrite`	Overwrite existing file if present
`--etag`	Expected ETag for conditional download (If-None-Match)
`--checksum`	Expected checksum for verification after download
`--checksum-algorithm`	Checksum algorithm: `sha256` (default), `sha384`, `sha512`

Output:

Downloaded file path
File size
API version (extracted from spec)
ETag for future conditional downloads
Checksum with verification status

Exit Codes

Code	Meaning
0	Success
1	Error or download failure
130	Operation cancelled by user

JSON Schema: ApiSpecDownloadResult

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "path": { "type": "string" },
    "sizeBytes": { "type": "integer" },
    "fromCache": { "type": "boolean" },
    "etag": { "type": "string" },
    "checksum": { "type": "string" },
    "checksumAlgorithm": { "type": "string" },
    "checksumVerified": { "type": "boolean" },
    "apiVersion": { "type": "string" },
    "generatedAt": { "type": "string", "format": "date-time" },
    "error": { "type": "string" },
    "errorCode": { "type": "string" }
  }
}

Examples

List available API specifications

# List all specs
stella api spec list

# List specs as JSON
stella api spec list --json

Download aggregate specification

# Download aggregate OpenAPI spec to current directory
stella api spec download --output ./

# Download with checksum verification
stella api spec download \
  --output ./stellaops-api.json \
  --checksum abc123def456... \
  --checksum-algorithm sha256

Download service-specific specification

# Download Scanner API spec
stella api spec download \
  --output ./scanner-api.yaml \
  --service scanner \
  --format openapi-yaml

Conditional download with ETag

# First download captures ETag
stella api spec download --output ./api.json --json > download-result.json

# Subsequent downloads use ETag for cache validation
ETAG=$(jq -r '.etag' download-result.json)
stella api spec download \
  --output ./api.json \
  --etag "$ETAG"

CI/CD Integration

#!/bin/bash
# Download and validate API spec in CI

stella api spec download \
  --output ./openapi.json \
  --checksum "$EXPECTED_CHECKSUM" \
  --json > result.json

if [ "$(jq -r '.checksumVerified' result.json)" != "true" ]; then
  echo "API spec checksum verification failed!"
  exit 1
fi

# Generate client code from spec
npx openapi-generator-cli generate \
  -i ./openapi.json \
  -g typescript-fetch \
  -o ./generated-client

Available Services

Service	Description
`aggregate`	Combined specification from all services (default)
`concelier`	Vulnerability advisory and VEX management
`scanner`	Container scanning and SBOM generation
`policy`	Policy engine and evaluation
`authority`	Authentication and authorization
`attestor`	Attestation generation and verification
`notify`	Notification delivery
`scheduler`	Job scheduling

Best Practices

Use ETag for conditional downloads to minimize bandwidth and improve CI performance
Verify checksums when downloading specs for code generation in production pipelines
Download aggregate spec for general client generation; service-specific specs for targeted APIs
Store ETags in CI cache to enable incremental downloads
Use YAML format for human readability; JSON for programmatic processing