feat: Implement console session management with tenant and profile handling
- Add ConsoleSessionStore for managing console session state including tenants, profile, and token information. - Create OperatorContextService to manage operator context for orchestrator actions. - Implement OperatorMetadataInterceptor to enrich HTTP requests with operator context metadata. - Develop ConsoleProfileComponent to display user profile and session details, including tenant information and access tokens. - Add corresponding HTML and SCSS for ConsoleProfileComponent to enhance UI presentation. - Write unit tests for ConsoleProfileComponent to ensure correct rendering and functionality.
This commit is contained in:
231
docs/export-center/cli.md
Normal file
231
docs/export-center/cli.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user