CLI reference

Use the CLI when you need safe machine-readable reproduction results from the local StatePort runtime. This page is generated from exact public command, outcome, and exit-code declarations.

Commands

auth
auth bind <capsule-path>
auth delete
auth status <capsule-path>
capture
inspect <capsule-path>
mcp
mcp config
open <capsule-path>
run <capsule-path>
state
state apply-request-remap <session-id> <evidence-id>
state auth-requirement <state-card-id>
state auth-status <state-card-id>
state console <state-card-id>
state export <state-card-id>
state history <state-card-id>
state import <source>
state inspect <state-card-id>
state journey <state-card-id>
state journey-action <state-card-id>
state list
state remove-request-remap <session-id> <evidence-id>
state request-changes <session-id>
verify <capsule-path>

Options

--after <count>
--api <absolute-pattern>
--card-only
--compare-to <run-path>
--confirm
--cursor <sequence>
--digest <sha256>
--expires-in-days <days>
--frontend <origin>
--height <pixels>
--level <level>
--limit <count>
--link
--max-body-bytes <positive-integer>
--max-capsule-bytes <positive-integer>
--name <name>
--out <directory>
--out <file>
--overlay <path>
--persona <persona-id>
--persona <persona-json>
--project <project-id>
--redact-json-path <direction:pointer>
--scope <scope>
--source <frontend-url>
--storage-key <area:key>
--storage-key <key>
--target <origin>
--volatile-query <name>
--width <pixels>

Reproduction results

Direct open and run commands return qualified evidence from run-artifact/0.6.0, or run-artifact/0.7.0 when request-change evidence is present. The exit map is:

exit code 0 — confirmed reproduction;
exit code 5 — every non-confirmed terminal result, effective user rejection, or adapter timeout;
exit code 2 — invalid arguments or an unsupported schema or artifact version;
exit code 3 — artifact integrity failure.

The interactive State Card Journey command returns the persisted state-card-reproduction-outcome/1.0.0 machine result after the exact attempt is complete. Every result includes top-level attemptId, stateCardId, path, targetKind, and browserSessionMode; receipt is present only when verified run evidence exists. If the adapter deadline expires before that result can be read, it emits only this non-persisted adapter result and exits with code 5:

{"kind":"adapter_timeout","code":"REPRODUCTION_OUTCOME_UNAVAILABLE","path":"recorded_journey","targetKind":"local","browserSessionMode":"clean-session"}

An adapter timeout has no outcome status, reason, or receipt and is not a persisted reproduction outcome. Commands write safe JSON where documented by the CLI. They never accept captured credentials or browser-profile exports.

Changed requests

A request-change-evidence/1.0.0 result distinguishes an exact technical match, one bounded semantic change, a new request, an ambiguous candidate set, or an extra occurrence. Safe CLI operations inspect that trusted result and apply or remove a remap by its opaque evidence handle. Reusing a captured response checks frontend behavior only; it does not verify the new backend request. A configured live target reports only what that target returned now and does not establish historical backend equivalence.

State summaries expose captured production-page readiness only as a closed state, optional reason, and aggregate resource count. They never expose shell material.

A comparison reports bounded differences between compatible run evidence. It is not a verdict that the saved state was reached, that a bug reproduced, or that current code is correct.

Card transfer and Capture size

Use state export <state-card-id> --out <file> for an ordinary .scard file, or --link for a Share URL. Existing files are never overwritten. Link lifetime defaults to 7 days; --expires-in-days accepts 1, 7 or 30.

state import <source> previews a file or StatePort Share URL. After reviewing it, repeat with --confirm --digest <preview-digest>. Protected containers additionally require --card-only; protected values and Personas remain available for explicit acceptance in Desktop. The full Share URL is a bearer capability; keep it with its intended recipient.

Capture defaults to 1920 by 1080 CSS pixels. Override with --width <pixels> and --height <pixels> (integers from 320 to 7680).

A changed preview returns TRANSFER_CHANGED; inspect again before confirming. TRANSFER_FILE_EXISTS leaves the existing destination intact. TRANSFER_UNSUPPORTED_VERSION, TRANSFER_TOO_LARGE, and TRANSFER_INTEGRITY_FAILED reject incompatible, oversized, or damaged input before import. TRANSFER_PROTECTED_DECISION_REQUIRED requires the explicit Card-only choice or Desktop acceptance.