hopper-cli
Command-line tooling for inspecting, explaining, and managing Hopper programs.
This is the operator's interface to Hopper. Feed it hex-encoded account data and a program manifest and it will decode headers, explain fields, diff versions, plan migrations, decode receipts, and generate client SDKs. Works entirely offline by default, with optional RPC connectivity for live account fetching.
Install
Install the 0.3.0 release:
Registry availability is tracked on the release status page. To build from a source checkout:
# or: cargo run --locked -p hopper-cli -- help
Commands
Compile
hopper compile --emit <rust|ts|kt|py|go|c|rust-client|idl|codama|schema|manifest> [<manifest>|--package <name>|--program-id ...]
Emit lowered Rust, client SDKs, Hopper public IDL, Codama, or manifest
hopper compile --emit manifest --package <name> Generate hopper.manifest.json (the Effect ABI carrier) from package source
Verify
hopper verify [<manifest>] [<.so>] Check manifest integrity and report layout-anchor diagnostics
hopper verify --release <manifest> <.so> Require the exact versioned interface commitment in the ELF
hopper verify --package <name> Infer manifest and SBF binary from a workspace package
hopper verify --effects <bundle|dir> Effect gate: verify evidence bundles against the manifest's
published write contract (changed ⊆ acquired ⊆ authorized,
via the separately runnable Grillo verifier); any violation fails
hopper verify --authority-baseline <old-manifest> [--baseline-so <old.so> | --baseline-program <id>]
[--candidate-buffer <addr> | --candidate-program <id>] [--cluster <name|url>]
Authority gate: exit 2 when an instruction gains authority
(dropped signer, new writable, wider field ranges, removed PDA,
has_one, owner, or address binding, new CPI program), exit 3
for review; --authority-report / --authority-approval record
and approve a reviewed widening for that exact manifest pair
hopper publish-check --package <name> Run interface binding, docs, feature, client, and fuzz gates
hopper publish-idl --manifest <path> --program-id <pubkey> [--cluster <name>|--url <rpc>] [--yes] [--dry-run]
Publish a lossless Solana IDL v0.1.0 projection through Program Metadata
hopper publish-security --file security.json --program-id <pubkey> [--init] [--read] [--dry-run]
Publish, scaffold, or read back the security.txt record (seed "security")
hopper publish-manifest --manifest <path> --program-id <pubkey> [--read] [--dry-run]
Publish or read back the full Hopper manifest (seed "hopper-manifest")
Schema
hopper schema export Static account-schema format reference
hopper schema export --manifest <manifest> Normalize Hopper manifest JSON
hopper schema export --idl <manifest> Hopper public IDL JSON
hopper schema export --codama <manifest> Codama-shaped JSON
hopper schema export --anchor-idl <manifest> --program-id <pubkey> Conditional current Solana IDL v0.1.0 projection
hopper schema validate <manifest> Validate a program manifest
hopper schema diff @old-layout.json @new-layout.json Field-level diff between versions
Inspect
hopper inspect <hex> Raw header decode
hopper inspect layout <manifest> <hex> Decode fields using a program manifest
hopper inspect segments <hex> Segment registry map
hopper inspect receipt <hex> Decode a state receipt
Explain
hopper explain <hex> Human-readable headered-account explanation
hopper explain account <hex> Explicit headered-account explanation
hopper explain receipt <hex> Explain a receipt in plain English
hopper explain compat @old-layout.json @new-layout.json Explain compatibility report
hopper explain policy <pack> Explain a named policy pack
hopper explain layout <manifest> Explain layout fields, intents, fingerprint
hopper explain program <manifest> Explain entire program pipeline
hopper explain context <manifest> [--type <ContextName>] Explain instruction contexts and generated accessors
hopper explain instruction <manifest> <tag|name> Explain one instruction's accounts and policy
hopper explain <tx-signature> Decode a confirmed transaction against local or application-provisioned legacy manifests
hopper explain <program-id> Fetch an application-provisioned legacy manifest PDA and explain the program
Compatibility
hopper compat @old-layout.json @new-layout.json Compatibility report
hopper compat --why @old-layout.json @new-layout.json Compatibility report with explanation
hopper plan @old-layout.json @new-layout.json Migration plan with steps
Lifecycle
hopper init [path] Create a Hopper-native project scaffold with minimal, NFT, Token-2022, DeFi, or Quasar-port templates
hopper add [-i|-s|-e <name>] Scaffold instruction, state, or error files
hopper build [--host|--sbf] Build the current project (default: SBF)
hopper test Run host-side tests for the current project
hopper deploy [--dry-run] [--no-build] Quote live loader-v3 rent or build and deploy with Cargo.lock pinned
hopper upgrade --program-id <id> [--cluster <c>] Rebuild and upgrade a deployed program in place
hopper close --program-id <id> [--cluster <c>] Close a program or buffer and reclaim rent
hopper migrate --program-id <id> [--cluster <c>] Upgrade a program carrying a layout migration
hopper buffers <list|close> List or close stranded loader buffers
hopper dump [--no-build] Disassemble the built SBF binary
hopper clean [-a|--all] Remove generated build artifacts while preserving keypairs
Keys
hopper keys new <path> Generate a program/keypair json file
hopper keys list [<path>...] List pubkey and path for each keypair
hopper keys print <path> Print the base58 pubkey of a keypair
hopper keys sync <path> [--src <file.rs>] Sync declare_id! from a keypair pubkey
hopper keys pda <seed>... [--program <id>] Derive a PDA and canonical bump
Config
hopper config get <key> Read a saved Hopper CLI config value
hopper config set <key> <value> Write a saved Hopper CLI config value
hopper config list Show saved Hopper CLI config values
Transactions
hopper tx explain <signature> Fetch and explain an on-chain transaction
hopper tx send --program <id> ... Send one instruction with explicit metas and hex data, signed locally
hopper tx send --v1 ... Same, as a SIMD-0385 transaction v1 envelope (4,096 bytes, config mask)
hopper tx simulate <tx-base64> Simulate a pre-built transaction
hopper tx submit <tx-base64> Submit a pre-built transaction
Shell
hopper completions <shell> Emit bash, zsh, fish, or PowerShell completions
hopper version Print CLI version and linked schema version
Profiling
hopper profile bench Run the primitive benchmark lab and emit JSON/CSV artifacts
hopper profile elf <program.so> Static SBF symbols, CU-ish estimates, sections, flamegraph export
hopper profile elf <program.so> --baseline <folded.txt> --fail-on-growth <bytes> --fail-on-growth-pct <pct>
Size gate: exit 2 when .text grew past both thresholds
Contention
hopper contention <manifest> Per-instruction write-lock and signature footprint the
declaration fixes (no measurement), plus the accounts a
proven write set shows are read-only
hopper contention <manifest> --max-block-cost <CU> Fail (exit 1) over a ceiling: a CI gate
on declared lock footprint. Not a transaction's block
cost (the requested CU limit dominates that) and not
the compute a handler burns
Audit evidence
hopper audit-check [--strict] Verify content-addressed audit evidence, freshness, and blockers
Project Health
hopper lint Run Hopper project diagnostics
hopper lint zc Scan typed-context sources for zero-copy footguns
hopper lint --deny-escapes Policy-escape audit as CI errors (flags ledger-bypassing accessors)
hopper solana-check [--all] Check SBF crate shape and Hopper entrypoint invariants
hopper expand Show lowered macro output for the current project
hopper doctor Check toolchain and workspace health
hopper feature-gate [--cluster <c>] [--json] [--require <name-or-pubkey>]... Check finalized runtime prerequisites
Adversarial Testing
hopper fuzz generate --program <manifest> [--out <plan>] [--corpus <dir>]
Generate deterministic seeded cases and invariant hooks
hopper fuzz check --program <manifest> [--plan <plan>]
Fail when a committed case plan is stale
hopper fuzz run --program <manifest> --adapter <executable> [--plan <plan>]
Execute cases through an application adapter; fail closed on
missing results, skips, failures, or unchecked invariants
Direct aliases
hopper decode <hex> Alias for inspect
hopper segments <hex> Alias for inspect segments
hopper receipt <hex> Alias for inspect receipt / receipt
hopper diff @old-layout.json @new-layout.json Alias for schema diff
hopper schema-export Static account-schema format reference
Client SDK
hopper client gen --ts <manifest> Generate TypeScript client SDK
hopper client gen --kt <manifest> Generate Kotlin client SDK (org.sol4k)
hopper client gen --py <manifest> Generate Python client SDK
hopper client gen --go <manifest> Generate Go client SDK
hopper client gen --c <manifest> Generate C client header
hopper actions gen --program <manifest> --out api/actions Generate Solana Actions route scaffolds
hopper mobile gen --program <manifest> --target kotlin|react-native Generate mobile binding stubs
hopper test-gen security --program <manifest> Generate a security test matrix scaffold
Fetch
hopper fetch <program-id> [--rpc <url>] [--json] Read an application-provisioned legacy MANIFEST_SEED PDA
Interactive
hopper interactive <manifest> Interactive terminal explorer
hopper ui <manifest> Alias for interactive
Manager
hopper manager summary <manifest> Program overview
hopper manager identify <manifest> <hex> Identify account type
hopper manager decode <manifest> <hex> Decode all fields with values
hopper manager instruction <manifest> <tag|name> Instruction details and policies
hopper manager layouts <manifest> List all layouts with fields
hopper manager policies <manifest> List policy packs with mappings
hopper manager events <manifest> List events with fields
hopper manager fingerprints <manifest> Show all layout fingerprints
hopper manager compat <manifest> <hex-old> <hex-new> Compare two account versions
hopper manager receipt <hex> Decode a state receipt
hopper manager explain <manifest> Full human-readable summary
hopper manager diff <manifest> <hex-before> <hex-after> Semantic field-level diff
hopper manager simulate <manifest> <instruction> Preview instruction requirements
hopper manager fetch <program-id> [--rpc <url>] Read a legacy MANIFEST_SEED PDA and show its summary
hopper manager interactive <manifest> Interactive terminal explorer
compile --emit idl emits Hopper's public IDL; the current Solana IDL v0.1.0
projection is the separate schema export --anchor-idl path. That projection
is fail-closed and succeeds only when Hopper's wire and account surface is
losslessly representable. It currently refuses Cicada because its u16-prefixed
bounded route_data and dynamic remaining-account contract cannot be encoded
faithfully. The supplied --program-id is the expected address written at the
IDL's top level; this offline export does not query RPC or prove deployment.
The projection carries Hopper's exact wire discriminators and marks account
bodies with custom hopper-zero-copy-v1 serialization. Consumers therefore
need a Hopper-aware decoder rather than Anchor's Borsh codec.
The short compatibility, diff, and plan commands interpret unprefixed inputs as
inline layout JSON. Prefix file paths with @.
When run inside a Hopper package that already contains hopper.manifest.json,
hopper compile --emit rust can infer that local manifest automatically. Use
--package <name> to target another workspace member and --out <path> to
write the lowered preview instead of printing it.
Use hopper solana-check --all --build-sbf before publishing deployability
claims. It checks the same crate shape the Solana SBF workflow enforces:
cdylib output, exactly one Hopper backend feature, path-qualified SBF macros,
and a successful cargo build-sbf for each program crate. Actions, mobile, and
security-test commands are manifest-backed scaffolds unless a project extends
the generated files into a production workflow.
Docs: https://docs.rs/crate/hopper-cli
Support
Hopper is open-source Solana infrastructure. Public-goods support and donations
can be sent to solanadevdao.sol / F42ZovBoRJZU4av5MiESVwJWnEx8ZQVFkc1RM29zMxNT.
Donation URI: solana:F42ZovBoRJZU4av5MiESVwJWnEx8ZQVFkc1RM29zMxNT?label=solanadevdao.sol
License
Apache-2.0