git.stella-ops.org/docs/modules/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](api.md) and [Profiles](profiles.md) 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>` | `table` on TTY | Controls table 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.

## 5. CI recipe (GitHub Actions example)

```yaml
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](profiles.md)
- [Export Center API reference](api.md)
- [Export Center Architecture](architecture.md)
- [Aggregation-Only Contract reference](../../ingestion/aggregation-only-contract.md)

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