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

```bash
# 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)

```bash
# 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

```json
{
  "$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

```bash
# List all specs
stella api spec list

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

### Download aggregate specification

```bash
# 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

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

### Conditional download with ETag

```bash
# 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

```bash
#!/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