Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting Started

Build a program with the CLI

To write your own program you need the pina CLI and the external tools it drives, not this repository:

  • rustup: the scaffold’s rust-toolchain.toml selects the pinned nightly.
  • The Agave CLI, which provides cargo-build-sbf for pina build and solana for pina deploy.
  • Node.js with npx when you generate TypeScript or Dart clients.
  • The Surfpool CLI for pina dev; pina test embeds Surfpool’s SDK in the generated test package.
npm install --global @pina-rs/cli
pina init my_program
cd my_program
pina doctor               # checks every prerequisite above
pina keys new             # replace the shared placeholder program ID
pina migrations create --auto true  # track every contract; record the version-0 ABI baseline
pina build
pina test --unit
pina test
pina generate

Run pina keys new and pina migrations create --auto true before anything else. The migration policy lives in the manifest that command writes, not in pina.toml, so until it runs nothing is tracked and generated clients carry no version envelope; the baseline also records the program ID it belongs to. See the pina init reference for what the scaffold contains.

Work on Pina itself

Prerequisites

  • Rust nightly toolchain from rust-toolchain.toml
  • devenv (Nix-based environment)
  • gh (for GitHub workflows)

Setup

devenv shell
install:all

See pina init --help for options like --path and --force. The CLI reference documents every command, output contract, and automation workflow.

For agent-assisted project work, install the Pina skill.

If pnpm-workspace.yaml sets useNodeVersion, devenv shell activates the matching pnpm-managed node/npm/npx/corepack toolchain automatically.

Build and test

cargo build --all-features
cargo test

For a deterministic Docker build suitable for Solana’s verified-build workflow, install solana-verify 0.5.1, start Docker, commit the complete source tree, and run:

pina build --verify

This produces the canonical deploy artifact plus a hash-bound Pina build record. It does not perform on-chain verification. See pina build for the trust model, prerequisites, and limitations.

Common quality checks

lint:clippy
lint:format
verify:docs

Generate a Codama IDL

pina idl --path ./examples/counter_program --output ./codama/idls/counter_program.json

See Codama Workflow for end-to-end generation and external-project usage.

Before adapting an example for a program that controls assets, work through the Production Readiness gate. Examples demonstrate scoped framework behavior; they are not audited deployment templates.

Build this documentation

docs:build

The generated site is written to docs/book/.