stella api - Command Guide

Verified against source commit f261640997 on 2026-10-04 (UTC). The verification command and local runtime boundary are recorded at the end of this guide.

The stella api spec commands list and download the Gateway’s current OpenAPI specifications. Configure STELLAOPS_BACKEND_URL to the installation’s Gateway URL and use normal online settings. The Gateway owner is OpenApiAggregatorEndpoints in src/Router/StellaOps.Gateway.WebService.

The runtime composition uses specifications obtained from HELLO-registered services. A missing, unreachable or timed-out service contributes no specification to the merged document. Listing shows those service statuses. Successful retrieval establishes the returned runtime composition; it does not establish complete estate coverage. The curated static catalog at src/Api/StellaOps.Api.OpenApi/stella.yaml has a separate source and regeneration workflow.

List specifications

stella api spec list [--tenant <id>] [--json]

The client reads /api/openapi/aggregate, whose JSON envelope contains generatedAtUtc and services. Each service has a service name and status; available entries also carry spec. The client reads /openapi.json for merged document metadata.

JSON output contains success, specs and aggregate. Service entries report status, version, OpenAPI version, available formats, the JSON SHA-256 and a content-derived ETag. Unavailable entries have empty formats and no checksum or ETag. The merged entry reports the Gateway document’s version, SHA-256 and owner ETag. Service selection uses names returned by this command, such as scanner or policy-engine; a fixed service catalog is not assumed.

Download a specification

stella api spec download \
  --output <file-or-directory> \
  [--tenant <id>] \
  [--service <registered-name>] \
  [--format openapi-json|openapi-yaml] \
  [--overwrite] \
  [--etag <etag>] \
  [--checksum <checksum>] \
  [--checksum-algorithm sha256|sha384|sha512] \
  [--json]

Mode	Source	Output
Omitted service or `--service aggregate`, JSON	`/openapi.json`	Merged OpenAPI document
Omitted service or `--service aggregate`, YAML	`/openapi.yaml`	Merged OpenAPI document
`--service <registered-name>`	`/api/openapi/aggregate`	The selected entry’s OpenAPI document; YAML is converted locally

An output directory receives stellaops-openapi.json or .yaml for the merged mode and stellaops-<service>-openapi.json or .yaml for a service. An extensionless file path receives the selected format’s extension. Service names are matched without case sensitivity.

The client validates the document before replacing output. HTTP failure, an unavailable service, malformed content, checksum mismatch, a truncated response or cancellation preserves an existing good output. A successful download is staged beside the destination and then moved into place.

JSON results report success, path, sizeBytes, fromCache, etag, checksum, checksumAlgorithm, checksumVerified and apiVersion. Fresh service extraction also reports the owner envelope’s generatedAt timestamp. Failures report error and errorCode where available.

Cache and integrity behavior

Without --overwrite or --etag, an existing valid file is reused without an HTTP request. The result explicitly reports fromCache=true; this establishes local cache reuse. Invalid cached content fails and remains unchanged. A supplied checksum is checked for cached and fetched output.

--overwrite requests a fresh document. --etag requests revalidation, even without --overwrite. For merged documents, the client sends If-None-Match only when the output file exists. A 304 reuses the validated file. A changed document replaces it after validation. With no output file, the fetch is unconditional. ETags may be provided with or without their surrounding quotes.

Per-service ETags are SHA-256 values of the JSON specification extracted from the owner envelope. The client re-reads that envelope and compares the selected document’s ETag locally. The Gateway does not provide per-service conditional download routes. The JSON and YAML representations use the same service ETag; checksums cover the actual output bytes in the selected format.

# Obtain a fresh merged runtime document.
stella api spec download --output ./api.json --overwrite --json > download-result.json

# Revalidate the same file using the reported ETag.
ETAG=$(jq -r '.etag' download-result.json)
stella api spec download --output ./api.json --etag "$ETAG"

# Select a service name returned by list.
stella api spec download --output ./scanner-api.yaml --service scanner --format openapi-yaml

Exit codes are 0 for success, 1 for command/download failure and 130 for user cancellation. Parser errors return 2. The same client supplies the merged JSON input to stella advisoryai sources prepare; that command also prepares Doctor controls and leaves the reviewed docs manifest unchanged.

Verification boundary

The adjacent contract tests compile the current owner endpoint and aggregator sources into a loopback HTTP host. Registered CLI commands use the real BackendOperationsClient; frozen service documents enter through the owner’s IHttpClientFactory fan-out boundary. This verifies route and response compatibility, fresh retrieval, cache behavior and output preservation without deploying the shared estate.

Recheck from a source checkout:

pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/Cli/__Tests/StellaOps.Cli.Tests/StellaOps.Cli.Tests.csproj -Class "*ApiSpecGatewayContractTests" -BuildProjectReferences