600f3a7a3c
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Console CI / console-ci (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled
- Added graph.inspect.v1 documentation outlining payload structure and determinism rules. - Created JSON schema for graph.inspect.v1 to enforce payload validation. - Defined mapping rules for graph relationships, advisories, and VEX statements. feat(notifications): establish remediation blueprint for gaps NR1-NR10 - Documented requirements, evidence, and tests for Notifier runtime. - Specified deliverables and next steps for addressing identified gaps. docs(notifications): organize operations and schemas documentation - Created README files for operations, schemas, and security notes to clarify deliverables and policies. feat(advisory): implement PostgreSQL caching for Link-Not-Merge linksets - Created database schema for advisory linkset cache. - Developed repository for managing advisory linkset cache operations. - Added tests to ensure correct functionality of the AdvisoryLinksetCacheRepository.
236 lines
8.5 KiB
Markdown
236 lines
8.5 KiB
Markdown
# 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.
|
||
|
||
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.
|
||
|
||
## 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.
|