Pina CLI
The pina command scaffolds programs, extracts Codama IDLs, renders clients, reads bundled reference material, profiles compiled SBF binaries, and plans explicit deployments. It is designed for both interactive use and scripted or agent-driven discovery.
Install
Install the prebuilt npm package. It selects the native binary for the current operating system, CPU, and Linux C library:
npm install --global @pina-rs/cli
pina --version
Or install from crates.io with Rust:
cargo install pina_cli
pina --version
Inside this repository, enter the development shell and use the pina shortcut:
devenv shell
pina --help
The shortcut runs cargo run -p pina_cli -- ... against the checked-out source.
Command map
| Command | Purpose | Primary output |
|---|---|---|
pina init | Create a project-aware program scaffold | Files plus next steps |
pina lint | Run the official security lints via the lint driver | Compiler diagnostics and optional fixes |
pina locks | Report write-lock hotspots and conflicting instructions | Text or JSON |
pina map | Chart instructions, account locks, and conflicts | Self-contained HTML or JSON |
pina build | Build SBF, optionally with deterministic verification inputs | SBF, IDL, and optional build-record files |
pina verify | Compare deployments and record verified source | Status or transaction |
pina generate | Generate configured client ecosystems | Generated clients |
pina cpi | Generate a standalone Pina CPI crate from an IDL | Rust crate |
pina import | Import a foreign program’s IDL as a CPI crate | Rust crate with provenance |
pina test | Run native/Mollusk or SBF/Surfpool tests | Test runner output |
pina dev | Start an offline Surfpool watch/redeploy loop | Surfpool UI and logs |
pina idl | Extract a Codama root-node IDL | JSON |
pina docs | List or render bundled terminal docs | Terminal text |
pina keys | Inspect or explicitly change program identity | Text or JSON |
pina doctor | Diagnose project and toolchain readiness | Text or JSON |
pina explain | Explain which account check failed in a transaction | Text or JSON |
pina completions | Generate a shell completion script | Shell script |
pina profile | Estimate SBF compute cost, or trace it per line from tests | Text, JSON, folded stacks, or HTML |
pina rehearse | Replay real traffic against an upgrade before shipping it | Text or JSON |
pina deploy | Plan and execute an explicit cluster deployment | Plan or JSON |
pina generate | Generate IDLs and Rust, CPI, JavaScript, Dart, and CLI clients | Generated directories |
Discover the interface
The help tree is intentionally self-describing:
pina --help
pina build --help
pina verify --help
pina verify check --help
pina verify record --help
pina verify submit --help
pina verify status --help
pina generate --help
pina cpi --help
pina idl --help
pina docs --help
pina init --help
pina lint --help
pina locks --help
pina map --help
pina keys --help
pina doctor --help
pina explain --help
pina completions --help
pina profile --help
pina rehearse --help
pina deploy --help
Long help includes the input contract, output behavior, defaults, and copyable examples. Run pina docs with no topic to discover the bundled architecture references.
Streams and exit codes
| Command | stdout | stderr |
|---|---|---|
idl | JSON when --output is omitted | Progress, extraction counts, errors |
docs | Topic index or rendered Markdown | Errors |
init | Created path and next steps | Errors |
lint | Completion summary | Cargo progress and lint diagnostics |
locks | Lock report or JSON | Errors and denied hotspots |
map | Written HTML path, or JSON | Progress and errors |
build | Published artifact summary | Cargo output and errors |
verify check | Matching hash | Mismatch hashes and errors |
verify record | Upstream streamed progress | Upstream diagnostics and errors |
generate | IDL and client summary | Renderer output and errors |
cpi | Generated crate summary | Conversion and renderer errors |
test | Child test-runner output | Build output and errors |
dev | Surfpool UI and logs | Build output and errors |
keys | Identity report or change summary | Errors |
doctor | Diagnostic report | Errors |
explain | Explanation report | Errors |
completions | Completion script | Errors |
profile | Report when --output is omitted | Errors; trace adds build and test output and warnings |
rehearse | Rehearsal report (text or JSON) | Progress and errors |
deploy | Plan, rehearsal, and completion | Confirmation, progress, errors |
codama generate | Completion summary | Errors and renderer failures |
Successful commands exit with code 0. Operational failures exit with code 1. Completed comparisons that find a difference exit with code 2: verification hash mismatches, profile compare regressions, and rehearse behaviour changes. rehearse exits with code 3 when it could compare no transaction. deploy --rehearse stops before sending anything with the same codes: 2 for behaviour changes, and 3 when nothing was compared or the program is not deployed yet. Invalid command-line syntax is rejected by Clap with a non-zero usage error before an operation begins.
For reliable automation, capture stdout only when the command documents it as machine-readable. See Automation and Agent Usage for a compact discovery protocol.
Path behavior
Relative paths are resolved from the process working directory. Project-aware commands discover the nearest pina.toml or unambiguous Cargo package and use Cargo metadata for the library source and target directory. Output commands create their documented output directories where applicable, but pina idl --output expects the parent directory to exist. Identity replacement requires pina keys new --force; profile reports are published atomically and cannot alias the input binary.
Environment
Project-aware commands read pina.toml and respect standard Cargo variables such as CARGO_TARGET_DIR and CARGO. The CLI also reads these Pina-specific optional environment variables:
| Variable | Used by | Meaning |
|---|---|---|
PINA_TEMPLATES_DIR | pina docs | Directory containing custom <topic>.t.md files |
PINA_SURFPOOL | pina dev, pina rehearse | Surfpool executable to run instead of surfpool |
No configuration file is required for an unambiguous Cargo package. pina init creates a small pina.toml so every tool and agent discovers the same program and client choices.
Agents that maintain Pina projects can install the companion @pina-rs/skill package.