git.stella-ops.org/docs/export-center/cli.md

Stella CLI - Export Center Commands

Audience: Operators, release engineers, and CI maintainers using the stella CLI to manage Export Center profiles and runs.
Supported from: stella CLI >= 0.22.0 (Export Center Phase 1).
Prerequisites: Authority token with the scopes noted per command (export:profile:manage, export:run, export:read, export:download).

Use this guide with the Export Center API reference and Profiles catalogue. The CLI wraps the same REST endpoints, preserving deterministic behaviour and guardrails.

Status: CLI support is tracked under CLI-EXPORT-35-001 and CLI-EXPORT-36-001. The current CLI build does not yet surface these commands; treat this guide as the target contract and adjust once implementations merge.

1. Global options and configuration

Flag	Default	Description
--server <url>	https://stella.local	Gateway root. Matches STELLA_SERVER.
--tenant <id>	Token tenant	Override tenant for multi-tenant tokens.
--profile <name>	none	Loads saved defaults from ~/.stella/profiles/<name>.toml.
--output <file>	stdout	Redirect full JSON response.
`--format <table	json	yaml>`
--trace	false	Emit request timing and correlation ids.

Environment variables: STELLA_TOKEN, STELLA_SERVER, STELLA_TENANT, STELLA_PROFILE.

Exit codes align with API error codes (see section 6).

2. Profile management commands

2.1 stella export profile list

List profiles for the current tenant.

stella export profile list --kind json --variant raw --format table

Outputs columns PROFILE, KIND, VARIANT, DISTRIBUTION, RETENTION. Use --format json for automation.

2.2 stella export profile show

stella export profile show prof-json-raw --output profile.json

Fetches full configuration and writes it to file.

2.3 stella export profile create

stella export profile create --file profiles/prof-json-raw.json

JSON schema matches POST /api/export/profiles. CLI validates against built-in schema before submission. Requires export:profile:manage.

2.4 stella export profile update

stella export profile update prof-json-raw \
  --retention "days:21" \
  --distribution http,object

Supports toggling retention, adding/removing distribution targets, and renaming. Structural changes (kind, variant, include set) require editing the JSON and using --replace-file to create a new revision.

2.5 stella export profile archive

stella export profile archive prof-json-raw --reason "Superseded by Phase 2 profile"

Marks the profile inactive. Use stella export profile restore to re-activate.

3. Run lifecycle commands

3.1 stella export run submit

stella export run submit prof-json-raw \
  --selector tenant=acme \
  --selector product=registry.example.com/app:* \
  --selector time=2025-10-01T00:00:00Z,2025-10-29T00:00:00Z \
  --policy-snapshot policy-snap-42 \
  --allow-empty=false

Selectors accept key=value pairs; use time=<from>,<to> for windows. The command prints the runId and initial status.

3.2 stella export run ls

stella export run ls --profile prof-json-raw --status active --tail 5

Shows recent runs with columns RUN, PROFILE, STATUS, PROGRESS, UPDATED.

3.3 stella export run show

stella export run show run-20251029-01 --format json

Outputs full metadata, progress counters, distribution descriptors, and links.

3.4 stella export run watch

stella export run watch run-20251029-01 --follow

Streams server-sent events and renders a live progress bar. --json prints raw events for scripting.

3.5 stella export run cancel

stella export run cancel run-20251029-01 --reason "Replacing with refined selectors"

Gracefully cancels the run; exit code 0 indicates cancellation request accepted.

4. Download and verification commands

4.1 stella export download

stella export download run-20251029-01 \
  --output out/exports/run-20251029-01.tar.zst \
  --resume

Downloads the primary bundle. --resume enables HTTP range requests; the CLI checkpoints progress to .part files.

4.2 stella export manifest

stella export manifest run-20251029-01 --output manifests/export.json

Fetches the signed manifest. Use --signature manifests/export.json.sig to save the detached signature.

4.3 stella export provenance

stella export provenance run-20251029-01 --output manifests/provenance.json

Retrieves the signed provenance file. --signature behaves like the manifest command.

4.4 stella export verify

stella export verify run-20251029-01 \
  --manifest manifests/export.json \
  --provenance manifests/provenance.json \
  --key keys/acme-export.pub

Wrapper around cosign verify. Returns exit 0 when signatures and digests validate. Exit 20 when verification fails.

5. CI recipe (GitHub Actions example)

name: Export Center Bundle
on:
  workflow_dispatch:
jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Stella CLI
        run: curl -sSfL https://downloads.stellaops.org/cli/install.sh | sh
      - name: Submit export run
        env:
          STELLA_TOKEN: ${{ secrets.STELLA_TOKEN }}
        run: |
          run_id=$(stella export run submit prof-json-raw \
            --selector tenant=acme \
            --selector product=registry.example.com/app:* \
            --allow-empty=false \
            --format json | jq -r '.runId')
          echo "RUN_ID=$run_id" >> $GITHUB_ENV
      - name: Wait for completion
        env:
          STELLA_TOKEN: ${{ secrets.STELLA_TOKEN }}
        run: |
          stella export run watch "$RUN_ID" --json \
            | tee artifacts/run.log \
            | jq -e 'select(.event == "run.succeeded")' > /dev/null
      - name: Download bundle
        env:
          STELLA_TOKEN: ${{ secrets.STELLA_TOKEN }}
        run: |
          stella export download "$RUN_ID" --output artifacts/export.tar.zst --resume
          stella export manifest "$RUN_ID" --output artifacts/export.json --signature artifacts/export.json.sig
          stella export provenance "$RUN_ID" --output artifacts/provenance.json --signature artifacts/provenance.json.sig
      - name: Verify signatures
        run: |
          stella export verify "$RUN_ID" \
            --manifest artifacts/export.json \
            --provenance artifacts/provenance.json \
            --key keys/acme-export.pub

6. Exit codes

Code	Meaning
0	Command succeeded.
10	Validation error (ERR_EXPORT_001).
11	Profile missing or inaccessible (ERR_EXPORT_002).
12	Quota or concurrency exceeded (ERR_EXPORT_003 or ERR_EXPORT_QUOTA).
13	Run failed due to adapter/signing/distribution error.
20	Verification failure (stella export verify).
21	Download incomplete after retries (network errors).
30	CLI configuration error (missing token, invalid profile file).

Exit codes above 100 are reserved for future profile-specific tooling.

7. Offline usage notes

• Use profiles that enable object distribution with local object storage endpoints. CLI reads STELLA_EXPORT_OBJECT_ENDPOINT when provided (falls back to gateway).
• Mirror bundles work offline by skipping OCI distribution. CLI adds --offline to bypass OCI checks.
• stella export verify works fully offline when provided with tenant public keys (packaged in Offline Kit).

8. Related documentation

• Export Center Profiles
• Export Center API reference
• Export Center Architecture
• Aggregation-Only Contract reference

Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.