hopper-cli 0.3.2

Command-line tooling for Hopper account inspection, schema export, and migration planning
hopper-cli-0.3.2 is not a library.

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.1 release:

cargo install hopper-cli --version 0.3.2 --locked

Registry availability is tracked on the release status page. To build from a source checkout:

cargo install --path tools/hopper-cli --locked
# 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