Reference

rustag CLI

Every rustag subcommand, with the exact flags from the clap definitions. Phase 1 is the working local MVP; Phase 2 and Phase 3 subcommands ship in the same binary and are newer.

Conventions

-s, --stagenet <NAME> selects which stagenet a command targets. It is optional when only one stagenet exists.
A global --log-format text|json (env RUSTAG_LOG_FORMAT, default text) applies to every command.
Client commands (airdrop, override, preload, logs, status) reach a running stagenet over its REST API; start one first with rustag start.

Phase 1 — core Phase 1 · Stable

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. Falls back to a built-in default if unset.
--no-mirror	off	Fully offline stagenet (no mainnet fetches).

rustag start [NAME]

Run the JSON-RPC, WebSocket, and REST servers (long-running, foreground). NAME is optional if only one stagenet exists.

Flag	Arity	Meaning
--preload <NAMES…>	variadic	Extra programs/oracles to preload on startup (e.g. --preload jupiter pyth). Merged with RustAG.toml preload targets.

bash

rustag create alt --rpc-port 18899 --api-port 19000rustag start alt --preload jupiter pyth raydium

rustag stop · status · list

rustag stop [-s NAME] — stop a running stagenet (best-effort via its ./.rustag/<name>.pid file; on Windows filtered to the rustag.exe image so a recycled PID is never killed).
rustag status [-s NAME] — show id, running state, RPC/REST URLs, mainnet RPC, mirror enabled/disabled, and account/transaction counts.
rustag list — list all stagenets (NAME, ID, RPC, STATUS). No flags.

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

Credit SOL to a wallet via the running stagenet. Positional <PUBKEY> (validated) and <SOL> (f64). 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 — at least one is required.

Flag	Type	Meaning
--pubkey <PUBKEY>*	Pubkey	Account to override.
--lamports <N>	u64	Set the lamport balance.
--token-balance <N>	u64	Set an SPL token account's raw amount.

bash

rustag override -s demo --pubkey <PUBKEY> --lamports 5000000000rustag override -s demo --pubkey <TOKEN_ACCOUNT> --token-balance 1000000

rustag preload [-s NAME] [PROGRAMS…]

Load known mainnet programs/oracles via the running stagenet. With no positional args it prints the available targets:

text

jupiter  pyth  raydium  orca  marinade  spl-token  token-2022  metaplex

rustag logs [-s NAME] [-f]

Tail the transaction feed. -f, --follow keeps streaming new transactions until Ctrl-C; without it, prints recent history and exits.

rustag doctor [-s NAME]

Preflight diagnostics: data dir writable, database openable, mainnet RPC reachable, and the stagenet's ports free (or held by the running stagenet). Exits non-zero on any hard failure.

Phase 2 Phase 2 · Preview

rustag schedule [-s NAME] <SUBCOMMAND>

Manage recurring on-chain activities to simulate realistic, ongoing usage.

add <NAME> <SCHEDULE> — <SCHEDULE> is @every 30s / @hourly / a 5-field cron (*/5 * * * *). Action flags (pick one): --airdrop <PUBKEY>; --transfer-from <SECRET> --to <PUBKEY>; or --raw-tx <BASE64>. --sol <N> sets the amount (default 1.0).
list — list all activities with last-run status.
rm <ID> — remove an activity by id.
toggle <ID> [--off] — enable an activity, or --off to disable it.

bash

rustag schedule -s demo add nightly "@every 30s" --airdrop <PUBKEY> --sol 5rustag schedule -s demo add swap "*/5 * * * *" --raw-tx <BASE64_SIGNED_TX>rustag schedule -s demo listrustag schedule -s demo toggle <ID> --offrustag schedule -s demo rm <ID>

rustag metrics [-s NAME]

Show analytics time-series for a stagenet.

Flag	Default	Meaning
--series <S>	all	Restrict to one series (e.g. tvl_lamports, transactions, accounts).
--limit <N>	20	Most-recent points to fetch per series.

Phase 3 Phase 3 · Experimental

rustag attest [-s NAME]

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

Flag	Default	Meaning
-o, --out <PATH>	.rustag/<name>.attestation.json	Output file.
-k, --key <PATH>	.rustag/attest-key.json	Attester keypair (Solana JSON); created if missing.
-p, --program <ID>	from txs	Program id(s) exercised. Repeatable.
--slot <N>	tx count	Slot to record in the manifest.
--tx-limit <N>	100000	Cap on transactions folded into the tx-results root.

rustag verify <FILE> [-s NAME]

Verify an attestation offline; exits non-zero if INVALID. Positional <FILE> is the attestation JSON.

Flag	Type	Meaning
-s, --stagenet <NAME>	from file	Recompute the state root against this stagenet's accounts.
--signature-only	flag	Only check the signature; skip recomputing the state root.

rustag scan [-s NAME]

Scan recorded transactions for exploit signatures — a CI gate.

Flag	Default	Meaning
--limit <N>	1000	Most-recent transactions to scan.
--fail-on <SEVERITY>	off	Exit non-zero if any finding is ≥ this severity (info \| low \| medium \| high \| critical).

rustag tree --leaf <X>

Build an off-chain spl-account-compression-compatible concurrent Merkle tree (no stagenet/network needed) and print its root + proofs.

Flag	Default	Meaning
--depth <D>	14	Tree depth (capacity is 2^depth).
--buffer <N>	64	Root-history / changelog window size.
--leaf <X>	—	Leaf to append, in order. A 64-char hex string is a raw 32-byte node; anything else is keccak-256 hashed. Repeatable.
--prove <I>	—	Print an inclusion proof for leaf index I.

bash

rustag attest -s demo --program <PROGRAM_ID>rustag verify .rustag/demo.attestation.json -s demorustag scan -s demo --fail-on highrustag tree --depth 14 --leaf hello --leaf world --prove 0

Note

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

PreviousCore concepts Next SDK & API