Solana transaction simulation for builders and traders

The surfpool CLI starts local Surfnets, executes Runbooks, lists Runbooks from a workspace manifest, generates shell completions, and starts the Surfpool MCP server.

Commands

Command	Description
`surfpool start`	Start a local Surfnet. Alias: `surfpool simnet`
`surfpool run`	Execute a Runbook
`surfpool ls`	List Runbooks in the current workspace
`surfpool completions`	Generate shell completion scripts
`surfpool mcp`	Start the Surfpool MCP server

`surfpool start`

Starts a local Surfnet. If you run it in a Solana program directory, Surfpool can generate and execute Runbooks that deploy your programs.

surfpool start [OPTIONS]

Network & Ports

Flag	Short	Type	Default	Description
`--port <PORT>`	`-p`	integer	`8899`	Bind the JSON-RPC server to this port.
`--ws-port <PORT>`	`-w`	integer	`8900`	Bind the WebSocket server to this port.
`--host <HOST>`	`-o`	string	`127.0.0.1`	Bind RPC, WebSocket, and Studio services to this host.
`--rpc-url <RPC_URL>`	`-u`	string	none	Fork from this datasource RPC URL. Conflicts with `--network`. Can also be set with `SURFPOOL_DATASOURCE_RPC_URL`.
`--network <NETWORK>`	`-n`	enum	none	Fork from a predefined Solana network. Values: `mainnet`, `devnet`, `testnet`. Conflicts with `--rpc-url`.
`--offline`	none	boolean	`false`	Run without a remote RPC datasource.

Project & Deployment

Flag	Short	Type	Default	Description
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Path to the runbook manifest.
`--no-deploy`	none	boolean	`false`	Disable automatic program deployments.
`--runbook <RUNBOOK>`	`-r`	string[]	`deployment`	Runbook ID to execute after startup. Repeatable.
`--runbook-input <INPUT_PATH>`	`-i`	path[]	none	Input file to provide to runbook execution. Repeatable.
`--yes`	`-y`	boolean	`false`	Skip runbook generation prompts.
`--watch`	none	boolean	`false`	Redeploy when program artifacts change.
`--artifacts-path <ARTIFACTS_PATH>`	none	path	none	Directory containing `.so` program artifacts. Defaults to `target/deploy` when omitted.
`--legacy-anchor-compatibility`	none	boolean	`false`	Use defaults suited for legacy Anchor test suites.
`--anchor-test-config-path <TEST_TOML>`	none	path[]	none	Anchor `Test.toml` file to inspect. Repeatable.

Accounts & State

Flag	Short	Type	Default	Description
`--airdrop <PUBKEY>`	`-a`	pubkey[]	none	Pubkey to airdrop SOL to at startup. Repeatable.
`--airdrop-keypair-path <KEYPAIR_PATH>`	`-k`	path[]	`~/.config/solana/id.json`	Keypair path whose pubkey should receive an airdrop. Repeatable.
`--airdrop-amount <LAMPORTS>`	`-q`	integer	`10000000000000`	Lamports to airdrop to each startup account.
`--snapshot <SNAPSHOT_PATH>`	none	path[]	none	JSON account snapshot to preload. Repeatable. Later files override earlier files for duplicate keys.
`--db <DB_URL>`	none	string	none	Database connection URL for persistent Surfnet state. Use `:memory:` for in-memory SQLite, a `.sqlite` file for on-disk SQLite, or a PostgreSQL URL when built with the `postgres` feature.
`--surfnet-id <SURFNET_ID>`	none	string	`default`	Storage namespace for this Surfnet instance.

Runtime & UI

Flag	Short	Type	Default	Description
`--no-tui`	none	boolean	`false`	Print logs instead of launching the terminal UI.
`--no-studio`	none	boolean	`false`	Disable Surfpool Studio.
`--studio-port <PORT>`	`-s`	integer	`18488`	Bind Studio to this port.
`--daemon`	none	boolean	`false`	Run Surfpool as a background process. Daemon mode is Linux-only.
`--ci`	none	boolean	`false`	Use settings suitable for CI. This disables the TUI, Studio, instruction profiling, and log output.

SVM Behavior

Flag	Short	Type	Default	Description
`--slot-time <MILLISECONDS>`	`-t`	integer	`400`	Slot time in milliseconds.
`--block-production-mode <MODE>`	`-b`	enum	`clock`	Block production mode.
`--feature <FEATURE_PUBKEY>`	`-f`	pubkey[]	none	Enable an SVM feature by pubkey. Repeatable. Feature names are deprecated but still accepted for previously supported names.
`--disable-feature <FEATURE_PUBKEY>`	none	pubkey[]	none	Disable an SVM feature by pubkey. Repeatable. Feature names are deprecated but still accepted for previously supported names.
`--features-all`	none	boolean	`false`	Enable all SVM features from `agave-feature-set`.
`--skip-signature-verification`	none	boolean	`false`	Skip transaction signature verification.
`--skip-blockhash-check`	none	boolean	`false`	Skip transaction blockhash validation.

Observability & Performance

Flag	Short	Type	Default	Description
`--geyser-plugin-config <PLUGIN_CONFIG_PATH>`	`-g`	path[]	none	Geyser plugin config file to load. Repeatable.
`--disable-instruction-profiling`	none	boolean	`false`	Disable instruction profiling.
`--max-profiles <COUNT>`	`-c`	integer	`200`	Transaction profiles to retain in memory. Higher values increase memory usage.
`--log-bytes-limit <BYTES>`	none	integer	`10000`	Maximum bytes stored for each transaction log. Set to `0` for unlimited logs.
`--log-level <LEVEL>`	`-l`	enum	`info`	Simnet log level. Values: `trace`, `debug`, `info`, `warn`, `error`, `none`.
`--log-path <LOG_DIR>`	none	path	`.surfpool/logs`	Directory for simnet logs.
`--metrics-enabled`	none	boolean	env: `SURFPOOL_METRICS_ENABLED`	Enable the Prometheus metrics endpoint. Available when Surfpool is built with the `prometheus` feature.
`--metrics-addr <METRICS_ADDR>`	none	string	`127.0.0.1:9000`	Prometheus metrics endpoint address. Can also be set with `SURFPOOL_METRICS_ADDR`. Available when Surfpool is built with the `prometheus` feature.

Deprecated Compatibility

Flag	Short	Type	Default	Description
`--subgraph-db <SUBGRAPH_DB>`	`-d`	string	`:memory:`	Deprecated and hidden from `surfpool start --help`. Existing scripts can still pass it for compatibility.

Examples

Start with default settings:

surfpool start

Fork devnet:

surfpool start --network devnet

Use a custom datasource RPC URL:

surfpool start --rpc-url https://api.mainnet-beta.solana.com

Print logs instead of launching the TUI:

surfpool start --no-tui

Start without a remote RPC datasource:

surfpool start --offline

Airdrop SOL to multiple accounts:

surfpool start --airdrop <PUBKEY> --airdrop <PUBKEY>

Load account state from snapshots:

surfpool start --snapshot ./snapshot1.json --snapshot ./snapshot2.json

Redeploy programs when target/deploy changes:

surfpool start --watch

Persist Surfnet state in an on-disk SQLite database:

surfpool start --db ./surfnet.sqlite --surfnet-id local-dev

`surfpool run`

Executes a Runbook. You can run a .tx file directly or reference a Runbook declared in a txtx.yml manifest.

surfpool run [OPTIONS] <RUNBOOK>

Arguments

Argument	Type	Description
`<RUNBOOK>`	string	Runbook ID from `txtx.yml`, or path to a `.tx` file.

Project

Flag	Short	Type	Default	Description
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Path to the runbook manifest.
`--env <ENVIRONMENT>`	none	string	none	Environment from `txtx.yml` to use.

Execution Mode

These flags are mutually exclusive. If none is specified, Surfpool uses browser supervision.

Flag	Short	Type	Default	Description
`--unsupervised`	`-u`	boolean	`false`	Execute without the supervisor UI.
`--browser`	`-b`	boolean	default mode	Execute with supervision in the browser UI.
`--terminal`	`-t`	boolean	`false`	Execute with supervision in the terminal console.

Inputs & Outputs

Flag	Short	Type	Default	Description
`--output-json [<OUTPUT_DIR>]`	none	optional path	none	Print or write Runbook outputs as JSON. When a directory is provided, output is written to a file in that directory.
`--output <OUTPUT_NAME>`	none	string	none	Print one named output at the end of execution. Conflicts with `--output-json`.
`--input <INPUT_PATH>`	none	path[]	none	Input file to use for batch processing. Repeatable.

Execution

Flag	Short	Type	Default	Description
`--explain`	none	boolean	`false`	Explain how the Runbook will execute.
`--force`	`-f`	boolean	`false`	Ignore cached execution state.

Supervisor UI

These flags are available when Surfpool is built with the supervisor_ui feature.

Flag	Short	Type	Default	Description
`--port <PORT>`	`-p`	integer	`8488`	Web UI port.
`--ip <IP_ADDRESS>`	`-i`	string	`127.0.0.1`	Web UI IP address.

Logging

Flag	Short	Type	Default	Description
`--log-level <LEVEL>`	`-l`	enum	`info`	Runbook execution log level. Values: `trace`, `debug`, `info`, `warn`, `error`.
`--log-path <LOG_DIR>`	none	path	`.surfpool/logs`	Directory for runbook execution logs.

Examples

Run a manifest Runbook with browser supervision:

surfpool run deployment

Run without supervision and write JSON outputs:

surfpool run deployment --unsupervised --output-json .surfpool/runbook-outputs

Run a .tx file directly:

surfpool run ./runbooks/deployment.tx

`surfpool ls`

Lists all Runbooks declared in the workspace manifest.

surfpool ls [OPTIONS]

Flag	Short	Type	Default	Description
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Path to the runbook manifest.

`surfpool completions`

Generates shell completion scripts.

surfpool completions <SHELL>

Argument	Type	Description
`<SHELL>`	enum	Shell to generate completions for. Values: `bash`, `elvish`, `fish`, `powershell`, `zsh`.

`surfpool mcp`

Starts the Surfpool MCP server for AI tool integration.

surfpool mcp

CLI Commands

Commands

`surfpool start`

Network & Ports

Project & Deployment

Accounts & State

Runtime & UI

SVM Behavior

Observability & Performance

Deprecated Compatibility

Examples

`surfpool run`

Arguments

Project

Execution Mode

Inputs & Outputs

Execution

Supervisor UI

Logging

Examples

`surfpool ls`

`surfpool completions`

`surfpool mcp`

On this page