Anchor CLI

A CLI is provided to support building and managing an Anchor workspace. For a comprehensive list of commands and options, run anchor -h on any of the following subcommands.

Usage: anchor [OPTIONS] <COMMAND>
 
Commands:
  init          Initializes a workspace
  build         Builds the workspace
  expand        Expands macros (wrapper around cargo expand)
  verify        Verifies the on-chain bytecode matches the locally compiled artifact. Run this command inside a program subdirectory, i.e., in the dir containing the program's Cargo.toml
  test          Runs integration tests
  fuzz          Coverage-guided fuzzing for Solana programs (powered by Crucible)
  new           Creates a new program
  debugger      Run tests under an instruction-level debugger
  coverage      Generate source-level coverage from SBF register traces
  idl           Commands for interacting with interface definitions
  clean         Remove all artifacts from the generated directories except program keypairs
  migrate       Runs the deploy migration script
  airdrop       Request an airdrop of SOL
  cluster       Cluster commands
  config        Configuration management commands
  shell         Starts a node shell with an Anchor client setup according to the local config
  run           Runs the script defined by the current workspace's Anchor.toml
  keys          Program keypair commands
  localnet      Localnet commands
  account       Fetch and deserialize an account using the IDL provided
  completions   Generates shell completions
  address       Get your public key
  balance       Get your balance
  epoch         Get current epoch
  epoch-info    Get information about the current epoch
  logs          Stream transaction logs
  show-account  Show the contents of an account
  keygen        Keypair generation and management
  program       Program deployment and management commands
  codama        Codama IDL integration commands
  legacy-idl    [DEPRECATED] Manage legacy on-chain IDL accounts. Migrate to Program Metadata-based IDL management (`anchor idl`)
  help          Print this message or the help of the given subcommand(s)
 
Options:
      --provider.cluster <CLUSTER>  Cluster override
      --provider.wallet <WALLET>    Wallet override
      --commitment <COMMITMENT>     Commitment override (valid values: processed, confirmed, finalized)
  -h, --help                        Print help
  -V, --version                     Print version

Account

anchor account <program-name>.<AccountTypeName> <account_pubkey>

Fetches an account with the given public key and deserializes the data to JSON using the type name provided. If this command is run from within a workspace, the workspace's IDL files will be used to get the data types. Otherwise, the path to the IDL file must be provided.

The program-name is the name of the program where the account struct resides, usually under programs/<program-name>. program-name should be provided in a case-sensitive manner exactly as the folder name, usually in kebab-case.

The AccountTypeName is the name of the account struct, usually in PascalCase.

The account_pubkey refers to the Pubkey of the account to deserialize, in Base58.

Example Usage: anchor account anchor-escrow.EscrowAccount 3PNkzWKXCsbjijbasnx55NEpJe8DFXvEEbJKdRKpDcfK, deserializes an account in the given pubkey with the account struct EscrowAccount defined in the anchor-escrow program.

anchor account <program-name>.<AccountTypeName> <account_pubkey> --idl <path/to/idl.json>

Deserializes the account with the data types provided in the given IDL file even if inside a workspace.

Build

anchor build

Builds programs in the workspace targeting Solana's BPF runtime and emitting IDLs in the target/idl directory.

anchor build --verifiable

Runs the build inside a docker image so that the output binary is deterministic (assuming a Cargo.lock file is used). This command must be run from within a single crate subdirectory within the workspace. For example, programs/<my-program>/.

Tip

It's possible to pass arguments to the underlying cargo build-sbf command with -- <ARGS>. For example:

anchor build -- --features my-feature

Cluster

Cluster list

anchor cluster list

This lists cluster endpoints:

Cluster Endpoints:
 
* Mainnet - https://api.mainnet-beta.solana.com
* Devnet  - https://api.devnet.solana.com
* Testnet - https://api.testnet.solana.com

Deploy

anchor deploy

Deploys all programs in the workspace to the configured cluster.

Tip

This is different from the solana program deploy command, because every time it's run it will generate a new program address.

Expand

anchor expand

If run inside a program folder, expands the macros of the program.

If run in the workspace but outside a program folder, expands the macros of the workspace.

If run with the --program-name option, expand only the given program.

Idl

The idl subcommand provides commands for interacting with interface definition files. Anchor uses the Program Metadata system to store IDLs on-chain at a deterministic address derived from the program's ID. This allows clients to be generated for a program using nothing but the program ID.

IDL management uses the @solana-program/program-metadata package instead of legacy IDL instructions. This results in smaller program binaries and a more standardized approach to on-chain metadata.

Idl Build

anchor idl build

Generates the IDL for the program using the compilation method.

Idl Init

anchor idl init -f <target/idl/program.json> [program-id]

Creates a metadata account containing the IDL for the given program. The IDL file is written to an account derived from the program ID.

anchor idl init -f <target/idl/program.json> <program-id> --non-canonical

Use the --non-canonical flag to create a third-party (non-canonical) metadata account. This is useful when you want to store metadata for a program you don't own.

The program-id argument is optional — when omitted, idl.address is used.

Idl Fetch

anchor idl fetch -o <out-file.json> <program-id>

Fetches an IDL from the configured blockchain. For example, make sure your
Anchor.toml is pointing to the mainnet cluster and run

anchor idl fetch GrAkKfEpTKQuVHG2Y97Y2FF4i7y7Q5AHLK94JBy7Y5yv

Use the --non-canonical flag to fetch third-party metadata:

anchor idl fetch <program-id> --non-canonical

Idl Upgrade

anchor idl upgrade -f <target/idl/program.json>

Upgrades the IDL file on chain to the new target/idl/program.json idl. The configured wallet must be the current authority. The program-id argument is optional — when omitted, idl.address is used.

Idl Close

anchor idl close <program-id>

Closes the metadata account and recovers the rent. By default, closes the "idl" seed account. Use --seed to specify a different seed:

anchor idl close <program-id> --seed <custom-seed>

Idl Create Buffer

anchor idl create-buffer -f <filepath>

Creates a buffer account for metadata. This is useful for large IDLs that need to be written across multiple transactions.

Idl Set Buffer Authority

anchor idl set-buffer-authority <buffer> -n <new-authority>

Sets a new authority on a buffer account.

Idl Write Buffer

anchor idl write-buffer <program-id> -b <buffer>

Writes metadata to the program using a pre-created buffer account. Use --seed to specify the metadata seed (defaults to "idl"):

anchor idl write-buffer <program-id> -b <buffer> --seed <seed>

Use --close-buffer to automatically close the buffer account after writing:

anchor idl write-buffer <program-id> -b <buffer> --close-buffer

Codama

anchor codama convert <target/idl/program.json> --out <codama-idl.json>
anchor codama generate -l rust,js -p clients <target/idl/program.json>

anchor codama convert converts an Anchor IDL into a Codama IDL. anchor codama generate converts the IDL and invokes the Codama renderer packages for the requested languages. The supported language values are js, js-umi, rust, and go.

Codama client generation can also run automatically after anchor build when [clients] auto = true is set in Anchor.toml.

Codama

anchor codama convert <target/idl/program.json> --out <codama-idl.json>
anchor codama generate -l rust,js -p clients <target/idl/program.json>

Codama client generation can also run automatically after anchor build when [clients] auto = true is set in Anchor.toml.

Init

anchor init <project-name>

Initializes a project workspace with the following structure.

Anchor.toml: Anchor configuration file.
Cargo.toml: Rust workspace configuration file.
package.json: JavaScript dependencies file.
programs/: Directory for Solana program crates.
app/: Directory for your application frontend.
tests/: Directory for JavaScript integration tests.
migrations/deploy.js: Deploy script.

By default, programs are initialized with a modular structure (multiple files) to promote better code organization. This is the recommended approach for production code.

Template Options:

anchor init --template multiple  # Default: Modular structure (recommended)
anchor init --template single     # Single lib.rs file (for prototyping)

The modular template organizes code into separate files for instructions, state, constants, and errors, making it easier to navigate and maintain as your program grows.

Anchor Version:

anchor init --anchor-version v1  # Default: Anchor v1 Rust templates
anchor init --anchor-version v2  # Anchor v2 Rust templates

The selected Anchor version controls the generated Rust program and Rust test template dependencies. V2 templates use the anchor-next git dependencies until the v2 crates are published.

Keys

Program keypair commands.

Keys List

anchor keys list

List all of the program keys.

Keys Sync

anchor keys sync

Sync program declare_id! pubkeys with the program's actual pubkey.

Migrate

anchor migrate

Runs the deploy script located at migrations/deploy.js, injecting a provider configured from the workspace's Anchor.toml. For example,

// File: migrations/deploys.js
 
const anchor = require("@anchor-lang/core");
 
module.exports = async function (provider) {
  anchor.setProvider(provider);
 
  // Add your deploy script here.
};

Migrations are a new feature and only support this simple deploy script at the moment.

New

anchor new <program-name>

Creates a new program in the workspace's programs/ directory initialized with boilerplate.

By default, uses the modular structure template (recommended). You can specify a different template with the --template flag:

anchor new --template multiple <program-name>  # Default: Modular (recommended)
anchor new --template single <program-name>    # Single file (for prototyping)

You can also select the Anchor Rust template version:

anchor new --anchor-version v1 <program-name>  # Default: Anchor v1 Rust templates
anchor new --anchor-version v2 <program-name>  # Anchor v2 Rust templates

Shell

anchor shell

Starts a node js shell with an Anchor client setup according to the local config. This client can be used to interact with deployed Solana programs in the workspace.

Test

anchor test

Run an integration test suit against the configured cluster, deploying new versions of all workspace programs before running them.

If the configured network is a localnet, then automatically starts the local network and runs the test. By default, Surfpool is used as the local network backend. To use solana-test-validator instead, pass --validator legacy.

Note

Be sure to shutdown any other local validators, otherwise anchor test will fail to run.

If you'd prefer to run the program against your local validator use anchor test --skip-local-validator.

When running tests we stream program logs to .anchor/program-logs/<address>.<program-name>.log

Use --profile with Rust/LiteSVM-style tests that enable the generated profile feature to collect SBF register traces and render flamegraph SVGs under target/anchor-v2-profile/.

Debugger

anchor debugger [test-name] [--skip-run] [--skip-build] [--gdb]

Runs tests with profiling enabled and opens an instruction-level TUI over the captured SBF traces. --skip-run reuses existing traces, and --gdb uses the sbpf gdb-stub trace path.

Coverage

anchor coverage [--skip-run] [--skip-build] [--output target/coverage/sbf.lcov]

Generates LCOV source coverage from SBF register traces. By default traces are collected under target/coverage/traces.

Upgrade

anchor upgrade <target/deploy/program.so> --program-id <program-id>

Uses Solana's upgradeable BPF loader to upgrade the on chain program code.

Verify

anchor verify <program-id>

Verifies the on-chain bytecode matches the locally compiled artifact.

Anchor CLI

On this page