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 the Profiles catalogue. The CLI wraps the same REST endpoints, preserving deterministic behaviour and guardrails end to end.

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>`	`table` on TTY	Controls output formatting for list commands.
`--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.

Integrity and determinism checks (EC1–EC10):

stella export manifest and provenance commands emit Digest/X-Stella-Signature headers; cache them for rerun-hash validation.
Offline kits: run docs/modules/export-center/operations/verify-export-kit.sh <kit_dir> to assert rerunHash, integrity headers vs OCI annotations, quotas/backpressure block, approvals, and log metadata in provenance.

4.5 `stella export nis2-soa`

Sprint 043 adds an offline-first NIS2 Statement of Applicability slice:

stella export nis2-soa \
  --since 2026-04-01 \
  --snapshot out/policy/nis2-control-register.json \
  --tenant tenant-a \
  --signing-key-file keys/offline-soa-hmac.key \
  --signing-key-id offline-soa-key \
  --evidence-locker-bundle-ref evidence-locker://bundles/sha256:... \
  --output out/nis2-soa.bundle.json \
  --json

The snapshot and signing key are local files so the command remains usable in air-gapped review:

--snapshot must contain a nis2-control-register-v1 Policy snapshot.
--tenant-profile may contain a local tenant-compliance-profile.v1 document with nis2 in regulatedRegimes.
When --tenant-profile is omitted, the CLI resolves the tenant from --tenant, STELLAOPS_TENANT, or the active CLI tenant profile and reads GET /api/v1/tenants/{tenantId}/compliance-profile from Authority. This path requires STELLAOPS_AUTHORITY_URL and an Authority token with authority:tenants.read.
--signing-key-file supplies the interim deterministic HMAC key for the DSSE-shaped envelope. This is the file-backed offline slice, not production compliance signing.
--redact-internal-only removes internal descriptions and metadata from exported controls.

The command writes a canonical nis2-soa-bundle-v1 JSON bundle containing the pinned control-register snapshot, the nis2-soa-v1 statement, manifest hashes, and DSSE envelope. The CLI verifies the generated bundle offline before writing success output. Production service integrations should use the adapter’s Signer/KMS-backed path instead of --signing-key-file; that path signs the canonical SoA through ICryptoProviderRegistry and verifies it with the centralized Signer EU offline verifier for payload type id nis2-soa-v1 and signer profile tenant-regulatory-export.

4.6 `stella export nis2-effectiveness`

Sprint 062 adds a deterministic monthly NIS2 effectiveness bundle:

stella export nis2-effectiveness \
  --month 2026-04 \
  --report out/platform/nis2-effectiveness-dashboard.json \
  --signing-key-file keys/nis2-effectiveness.hmac \
  --signing-key-id offline-nis2-effectiveness \
  --target-document-ref policy://target-documents/nis2/2026-04 \
  --control-register-snapshot-ref policy://control-registers/nis2/2026-04 \
  --policy-snapshot-ref policy://snapshots/nis2/2026-04 \
  --output out/nis2-effectiveness-tenant-a-202604.bundle.json \
  --json

The command consumes a local nis2-effectiveness-dashboard-v1 JSON report and writes a canonical nis2-effectiveness-report-bundle-v1 JSON bundle. The bundle contains the normalized source dashboard report, the nis2-effectiveness-report-v1 monthly report, fixed manifest entry hashes, and a DSSE-shaped signature over the monthly report bytes.

Fail-closed and truthfulness rules:

--report is required until live Platform export resolution is wired into this CLI path.
The source report must contain exactly 13 areas numbered 1 through 13.
Target document, control-register snapshot, and Policy snapshot refs should be supplied when available. Missing hashes/refs are preserved as report blockers instead of synthesized.
--signing-key-file supplies local HMAC key material, or STELLAOPS_NIS2_EFFECTIVENESS_HMAC_KEY may be used. This is an offline reproducibility and tamper-verification mechanism only; it is not production CAdES/KMS signing.

Verify a bundle offline:

stella verify nis2-effectiveness \
  --bundle out/nis2-effectiveness-tenant-a-202604.bundle.json \
  --signing-key-file keys/nis2-effectiveness.hmac \
  --signing-key-id offline-nis2-effectiveness \
  --json

Verification checks the bundle schema, manifest hashes, source report hash, monthly report hash, DSSE payload bytes, payload type, key id, and HMAC signature. Any tampering returns the CLI verification-failure exit code.

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