git.stella-ops.org/docs/modules/cli/guides/commands/api.md

stella api — Command Guide

Overview

The stella api command group provides API management capabilities including specification download and listing.

Commands

List API Specifications (CLI-SDK-63-001)

# 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 (CLI-SDK-63-001)

# 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

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