Reference

rustag CLI

Every rustag subcommand, with the exact flags. Phase 1 commands (rehearse, verify, serve) are the GroundTruth core — they ship and work today. Phase 2 (forensics, record) and Phase 3 (stagenet dev tools) are in the same binary.

Conventions

A global --log-format text|json (env RUSTAG_LOG_FORMAT, default text) applies to every command.
--rpc <URL> / env RUSTAG_MAINNET_RPC — the mainnet RPC endpoint for closure resolution. Required for live rehearsals; not needed for --demo or --offline.
All output paths default to the working directory. Use --out and --closure to customize.

Phase 1 — assurance core Phase 1 · Stable

rustag rehearse

The primary command. Fetches the proposal or payload, resolves the full account closure, runs the sealed two-pass rehearsal, and writes a signed EvidenceBundle + portable pre-state closure.

Flag	Default	Meaning
--proposal <PUBKEY>	—	multisig VaultTransaction proposal address. RustAG fetches, Borsh-decodes, and rehearses it.
--payload <BASE64>	—	Base64 bincode-serialized VersionedTransaction to rehearse directly.
--rpc <URL>	$RUSTAG_MAINNET_RPC	Mainnet RPC for closure resolution. Required for --proposal and --payload.
--offline	off	Skip the mirror entirely. The payload must be self-contained (no external accounts).
--demo	off	Run the built-in ownership-takeover demo. No RPC needed.
--signer <PATH>	ephemeral	Path to a Robinhood Chain JSON keypair (64-byte array) to sign the bundle with.
--out <PATH>	groundtruth-bundle.json	Where to write the signed EvidenceBundle.
--closure <PATH>	groundtruth-closure.json	Where to write the portable pre-state closure (needed for offline verify).
--fail-on <SEVERITY>	off	Exit non-zero if any alarm reaches this severity (info \| low \| medium \| high \| critical). Use in CI.

bash

# multisig proposalrustag rehearse \  --proposal 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU \  --rpc $ALCHEMY_RPC \  --fail-on high # Raw transactionrustag rehearse --payload <BASE64_TX> --rpc $RPC # Built-in demo (no network)rustag rehearse --demo

rustag verify <BUNDLE>

Verify an EvidenceBundle offline. Checks the Ed25519 signature, re-derives the pre-state root from the closure, and confirms fidelity grade. Exits non-zero if INVALID.

Flag	Type	Meaning
--closure <PATH>	groundtruth-closure.json	The portable pre-state closure to verify against.
--signature-only	flag	Only check the Ed25519 signature; skip re-deriving the state root.

bash

rustag verify groundtruth-bundle.json --closure groundtruth-closure.json

rustag serve

Start the REST API server (POST /api/rehearse, POST /api/verify, GET /api/health) for the dashboard and external integrations. Long-running foreground process.

Flag / Env	Default	Meaning
RUSTAG_MAINNET_RPC	—	Mainnet RPC URL. Required for live rehearsals via the API.
RUSTAG_BIND_HOST	127.0.0.1	Host to bind. Set to 0.0.0.0 on Render/Docker.
RUSTAG_DEMO_MODE	0	Cap airdrops and disable write operations (public demo safety).

bash

export RUSTAG_MAINNET_RPC="https://mainnet.alchemy.com/?api-key=YOUR_KEY"rustag serve           # REST API on $PORT or 9000

Phase 2 — forensics & corpus Phase 2 · Preview

rustag forensics <SIGNATURE>

Re-execute a historical mainnet transaction deterministically. In counterfactual mode, substitute the deployed program with a patched ELF and emit a BLOCKED or REPRODUCED verdict.

Flag	Type	Meaning
<SIGNATURE>	required	Base-58 transaction signature to fetch and re-execute.
--rpc <URL>	$RUSTAG_MAINNET_RPC	Mainnet RPC.
--patch <PATH>	—	Path to a patched program ELF to substitute before re-execution.
--patch-program <PUBKEY>	—	Program ID to patch. Required when --patch is set.
--json	off	Emit machine-readable JSON verdict instead of human text.

bash

# Re-execute a historical transactionrustag forensics <SIGNATURE> --rpc $RPC # Counterfactual: would this patch have stopped it?rustag forensics <SIGNATURE> \  --rpc $RPC \  --patch ./patched.so \  --patch-program <PROGRAM_ID>

rustag record

Build a real mainnet traffic corpus for a watched program — used as input to the upgrade-rehearsal CI gate.

Flag	Default	Meaning
--program <PUBKEY>*	—	Program to watch.
--rpc <URL>	$RUSTAG_MAINNET_RPC	Mainnet RPC.
--limit <N>	100	Max transactions to record.
--out <PATH>	corpus.json	Output corpus file.
--append	off	Append to an existing corpus file.

bash

rustag record --program <PROGRAM_ID> --rpc $RPC --out corpus.json --limit 500

Phase 3 — stagenet & dev tools Phase 3 · Experimental

Note

These commands manage a persistent local EVM stagenet — useful for integration testing and the dashboard. For pre-execution assurance, use rustag rehearse instead.

rustag create <NAME>

Flag	Default	Meaning
--rpc-port <PORT>	8899	JSON-RPC port.
--ws-port <PORT>	rpc_port + 1	WebSocket port.
--api-port <PORT>	9000	REST API port.
--mainnet-rpc <URL>	$RUSTAG_MAINNET_RPC	Endpoint the lazy mirror fetches from.
--no-mirror	off	Fully offline stagenet.

rustag start [NAME]

Run the JSON-RPC, WebSocket, and REST servers (long-running, foreground).

bash

rustag create demorustag start demo --preload oracle dex

rustag airdrop [-s NAME] <PUBKEY> <ETH>

Credit ETH to a wallet via the running stagenet. Airdrops are unlimited — capped only to prevent u64 overflow.

bash

rustag airdrop -s demo <YOUR_WALLET> 1000

rustag override [-s NAME] --pubkey <PK>

Set (and pin) account state via the running stagenet. Pass --lamports or --token-balance.

bash

rustag override -s demo --pubkey <PUBKEY> --lamports 5000000000

rustag schedule [-s NAME] <SUBCOMMAND>

Manage recurring on-chain activities (add, list, rm, toggle).

bash

rustag schedule -s demo add nightly "@every 30s" --airdrop <PUBKEY> --sol 5rustag schedule -s demo list

rustag attest [-s NAME]

Produce a signed, Merkle-rooted attestation of staged state (operates offline against the persisted store).

bash

rustag attest -s demo --program <PROGRAM_ID>rustag verify .rustag/demo.attestation.json -s demo

rustag scan [-s NAME]

Scan recorded transactions for exploit signatures — a CI gate.

bash

rustag scan -s demo --fail-on high

Note

Looking for the programmatic surface? See the SDK & API reference for @rustag/sdk, the REST contract, and the Robinhood Chain JSON-RPC methods the stagenet implements.

PreviousCore concepts Next SDK & API