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

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