Score & Proofs CLI Reference

Audience: DevOps engineers, security analysts, and CI authors working with score replay and proof bundles. Score contract update (PCD-429, 2026-10-07). The registered score group exposes Scanner replay, bundle metadata and verification, plus Signals digest explanation. See score replay commands for source pointers and re-verification. The proof-command sections below retain their separate scope.

Overview

The score replay, score bundle, and score verify commands call the configured Scanner owner through the Backend Router. stella score explain reads Signals by digest. These score commands require service connectivity; the registered score group has no offline replay flag. Proof-bundle commands are documented separately below.

Commands

stella score

Replay and verify Scanner scores, read bundle metadata, or explain a Signals digest.

stella score <SUBCOMMAND> [OPTIONS]

Subcommands

Subcommand	Description
`replay`	Replay scoring for a scan using its stored manifest
`bundle`	Read Scanner-side proof bundle metadata
`verify`	Verify a Scanner bundle against an expected root and optional canonical binding
`explain`	Read the Signals score explanation for a digest

stella score replay

Replay score computation for an existing scan through POST /api/v1/scans/{scanId}/score/replay.

stella score replay [OPTIONS]

Options

Option	Description	Default
`--scan`, `-s`	Scan identifier	Required
`--manifest-hash`, `-m`	Select stored manifest	Owner selection
`--freeze`, `-f`	ISO 8601 freeze timestamp	Manifest creation time
`--output`, `-o`	Format: `text`, `json`	`text`

Examples

stella score replay --scan 00000000-0000-0000-0000-000000000123 --output json
stella score replay --scan 00000000-0000-0000-0000-000000000123 --freeze 2026-10-06T00:00:00Z

stella score bundle

Read metadata through GET /api/v1/scans/{scanId}/score/bundle. The response carries scanId, rootHash, bundleUri, manifestDsseValid, and createdAt; the CLI does not download the server-side archive.

stella score bundle --scan 00000000-0000-0000-0000-000000000123 --output json

Options

Option	Description	Default
`--scan`, `-s`	Scan identifier	Required
`--output`, `-o`	Format: `text`, `json`	`text`

stella score verify

Verify a Scanner bundle through POST /api/v1/scans/{scanId}/score/verify.

stella score verify --scan <SCAN-ID> --root-hash <HASH> [OPTIONS]

Options

Option	Description	Default
`--scan`, `-s`	Scan identifier	Required
`--root-hash`, `-r`	Expected root hash; selects the scan’s stored bundle	Required
`--canonical-input-hash`	Expected canonical input hash	—
`--canonical-input-payload`	UTF-8 JSON file path, at most 1 MiB; exact text retained	—
`--output`, `-o`	Format: `text`, `json`	`text`

Examples

stella score verify --scan 00000000-0000-0000-0000-000000000123 --root-hash sha256:def456 --output json
stella score verify --scan 00000000-0000-0000-0000-000000000123 --root-hash sha256:def456 --canonical-input-hash sha256:abc123 --canonical-input-payload canonical-input.json

stella score explain

Read the Signals explanation for a digest through /api/v1/score/explain/{digest}.

stella score explain sha256:abc123 --format json

Options

Option	Description	Default
`--format`, `-f`	Format: `table`, `json`, `markdown`	`table`
`--server`	Backend Router URL	Configured backend

All four verbs accept --verbose. Scanner replay and verify request scanner:read scanner:write; bundle requests scanner:read. Signals explanation uses Score.Read and score.read. Score transport uses existing Authority credentials and the effective tenant. The common proof connection/environment tables below do not define score options.

Replay JSON preserves factor vectors, canonical input binding and verification status. Verification JSON preserves computed/expected roots, component validity flags, canonical hashes, verification time and owner error. HTTP 200 valid:false exits 2; provider and malformed-response failures emit sanitized success:false JSON without a fabricated domain result. The score replay guide describes exact payload handling, restart verification and the limits of route/DTO test evidence.

The legacy unregistered ScoreCommandGroup and its shape-only tests were withdrawn under PCD-429. Direct score compute, show, diff, manifest, inputs, history, and compare are not registered CLI verbs.

Proof Commands

stella proof

Manage proof bundles.

stella proof <SUBCOMMAND> [OPTIONS]

Subcommands

Subcommand	Description
`verify`	Verify a proof bundle
`download`	Download proof bundle
`export`	Export proof bundle
`inspect`	Inspect proof bundle contents
`status`	Check proof status
`list`	List proofs for a scan
`retrieve`	Retrieve from cold storage

stella proof verify

Verify a proof bundle.

stella proof verify [OPTIONS]

Options

Option	Description	Default
`--bundle-id <HASH>`	Proof bundle ID (sha256:…)	—
`--bundle <PATH>`	Local proof bundle file	—
`--offline`	Skip Rekor verification	`false`
`--skip-rekor`	Alias for --offline	`false`
`--check-rekor`	Force Rekor verification	`false`
`--trust-anchor <PATH>`	Trust anchor file	System default
`--public-key <PATH>`	Public key file	—
`--self-contained`	Use embedded trust anchors	`false`
`--verbose`	Show detailed verification	`false`
`--check <CHECK>`	Verify specific check only	All

Verification Checks

Check	Description
`signatureValid`	DSSE signature verification
`idRecomputed`	Content-addressed ID match
`merklePathValid`	Merkle tree construction
`rekorInclusion`	Transparency log entry

Examples

# Verify online
stella proof verify --bundle-id sha256:proof123...

# Verify offline
stella proof verify --bundle proof.zip --offline

# Verify with specific trust anchor
stella proof verify --bundle proof.zip --offline --trust-anchor anchors.json

# Verify specific check
stella proof verify --bundle-id sha256:proof123... --check signatureValid

stella proof download

Download proof bundle.

stella proof download [OPTIONS]

Options

Option	Description	Default
`--scan-id <ID>`	Scan ID	Required
`--root-hash <HASH>`	Specific proof root hash	Latest
`--output <PATH>`	Output file path	`proof-{scanId}.zip`
`--all`	Download all proofs for scan	`false`
`--output-dir <PATH>`	Output directory (with --all)	`.`

Examples

# Download latest proof
stella proof download --scan-id $SCAN_ID --output proof.zip

# Download specific proof
stella proof download --scan-id $SCAN_ID --root-hash sha256:proof123... --output proof.zip

# Download all proofs
stella proof download --scan-id $SCAN_ID --all --output-dir ./proofs/

stella proof export

Export proof bundle with additional data.

stella proof export [OPTIONS]

Options

Option	Description	Default
`--scan-id <ID>`	Scan ID	Required
`--portable`	Create self-contained portable bundle	`false`
`--include-manifest`	Include scan manifest	`true`
`--include-chain`	Include full proof chain	`false`
`--include-trust-anchors`	Include trust anchor keys	`false`
`--output <PATH>`	Output file path	Required

Examples

# Export standard bundle
stella proof export --scan-id $SCAN_ID --output proof-bundle.zip

# Export portable bundle (for offline verification)
stella proof export --scan-id $SCAN_ID --portable --include-trust-anchors --output portable.zip

# Export with full chain
stella proof export --scan-id $SCAN_ID --include-chain --output full-bundle.zip

stella proof inspect

Inspect proof bundle contents.

stella proof inspect [OPTIONS]

Options

Option	Description	Default
`--bundle <PATH>`	Proof bundle file	Required
`--output-dir <PATH>`	Extract to directory	—
`--show-manifest`	Display manifest	`false`
`--show-proof`	Display proof nodes	`false`
`--show-meta`	Display metadata	`false`

Examples

# List bundle contents
stella proof inspect --bundle proof.zip

# Extract and inspect
stella proof inspect --bundle proof.zip --output-dir ./inspection/

# Show manifest
stella proof inspect --bundle proof.zip --show-manifest

Common Options

Authentication

Option	Description
`--token <TOKEN>`	OAuth bearer token
`--token-file <PATH>`	File containing token
`--profile <NAME>`	Use named profile

Output

Option	Description
`--quiet`	Suppress non-error output
`--verbose`	Enable verbose output
`--debug`	Enable debug logging
`--no-color`	Disable colored output

Connection

Option	Description
`--endpoint <URL>`	Scanner API endpoint
`--timeout <DURATION>`	Request timeout (e.g., 30s, 5m)
`--insecure`	Skip TLS verification (dev only)

Environment Variables

Variable	Description	Equivalent Option
`STELLA_TOKEN`	OAuth token	`--token`
`STELLA_ENDPOINT`	API endpoint	`--endpoint`
`STELLA_PROFILE`	Profile name	`--profile`
`STELLA_OFFLINE`	Offline mode	`--offline`
`STELLA_TRUST_ANCHOR`	Trust anchor path	`--trust-anchor`

Exit Codes

The proof table below does not define score exit codes. Scanner score operations exit 0 on success, 2 on a valid verification refusal, and nonzero on operational failures. Signals explanation uses ScoreExitCodes; see score replay commands.

Code	Meaning
0	Success
1	General error
2	Invalid arguments
3	Authentication failed
4	Resource not found
5	Verification failed
6	Network error
10	Timeout