Solana transaction simulation for builders and traders

The surfpool CLI is used to start local Surfnets (Solana simulation networks), execute Runbooks, and manage cloud deployments.

surfpool start

Starts a local Surfnet. If run in a Solana program directory, Surfpool automatically generates Runbooks to deploy your programs.

surfpool start [OPTIONS]

Network Options

Flag	Short	Description	Default
`--port`	`-p`	Simnet RPC port	`8899`
`--ws-port`	`-w`	Simnet WebSocket port	`8900`
`--host`	`-o`	Simnet host address	`127.0.0.1`
`--slot-time`	`-t`	Slot time in milliseconds	`400`
`--block-production-mode`	`-b`	Block production mode: `clock`, `transaction`, or `manual`	`clock`
`--rpc-url`	`-u`	Datasource RPC URL (conflicts with `--network`)	-
`--network`	`-n`	Predefined network: `mainnet`, `devnet`, or `testnet` (conflicts with `--rpc-url`)	-
`--offline`	-	Start without remote RPC client	`false`

Deployment Options

Flag	Short	Description	Default
`--manifest-file-path`	`-m`	Path to the manifest	`./txtx.yml`
`--no-deploy`	-	Disable auto deployments	`false`
`--runbook`	`-r`	Runbook IDs to execute (repeatable)	`deployment`
`--runbook-input`	`-i`	Inputs for runbooks (repeatable)	-
`--yes`	`-y`	Skip prompts, assume "yes" for all	`false`
`--watch`	-	Watch `target/deploy` and re-deploy when `.so` files change	`false`
`--snapshot`	-	Path to JSON snapshot file(s) to preload accounts (repeatable)	-

Airdrop Options

Flag	Short	Description	Default
`--airdrop`	`-a`	Pubkeys to airdrop tokens to (repeatable)	-
`--airdrop-amount`	`-q`	Amount of lamports to airdrop	`10000000000000`
`--airdrop-keypair-path`	`-k`	Keypair paths to airdrop (repeatable)	`~/.config/solana/id.json`

UI Options

Flag	Short	Description	Default
`--no-tui`	-	Display logs instead of terminal UI dashboard	`false`
`--no-studio`	-	Disable Studio	`false`
`--studio-port`	`-s`	Studio port	`18488`

Logging & Profiling

Flag	Short	Description	Default
`--log-level`	`-l`	Log level: `trace`, `debug`, `info`, `warn`, `error`, `none`	`info`
`--log-path`	-	Directory for simnet logs	`.surfpool/logs`
`--disable-instruction-profiling`	-	Disable instruction profiling	`false`
`--max-profiles`	`-c`	Max transaction profiles held in memory	`200`
`--log-bytes-limit`	-	Max bytes allowed in transaction logs (0 = unlimited)	`10000`

Database Options

Flag	Short	Description	Default
`--db`	-	Surfnet database URL for persistence (`:memory:`, `.sqlite` file, or postgres URL)	-
`--surfnet-id`	-	Unique ID for this surfnet instance (isolates database storage)	`default`
`--subgraph-db`	`-d`	Subgraph database URL (sqlite `:memory:` or postgres)	`:memory:`

Plugin & Feature Options

Flag	Short	Description	Default
`--geyser-plugin-config`	`-g`	Geyser plugin config JSON files to load (repeatable)	-
`--feature`	`-f`	Enable specific SVM features (repeatable)	-
`--disable-feature`	-	Disable specific SVM features (repeatable)	-
`--features-all`	-	Enable all SVM features (overrides mainnet defaults)	`false`

Compatibility & CI

Flag	Short	Description	Default
`--ci`	-	CI mode: disables profiling, studio, tui; sets log level to none	`false`
`--daemon`	-	Start as background process (Linux only)	`false`
`--legacy-anchor-compatibility`	-	Apply defaults for Anchor test suite compatibility	`false`
`--anchor-test-config-path`	-	Path to `Test.toml` test suite files (repeatable)	-

Examples

Start with default settings:

surfpool start

Start with a specific datasource network and custom slot time:

surfpool start --network mainnet --slot-time 200

Start in CI mode:

surfpool start --ci

Start with airdrops and watch mode:

surfpool start -a MyPubkey123 --watch

surfpool run

Executes a Runbook. Can run a .tx file directly or reference a runbook declared in a txtx.yml manifest.

surfpool run [OPTIONS] <RUNBOOK>

Arguments

Argument	Description
`RUNBOOK`	Name of the runbook as indexed in `txtx.yml`, or path to a `.tx` file

Execution Mode

These flags are mutually exclusive. If none is specified, --browser is the default.

Flag	Short	Description
`--unsupervised`	`-u`	Execute without supervision
`--browser`	`-b`	Execute with browser UI supervision (default)
`--terminal`	`-t`	Execute with terminal supervision (coming soon)

Options

Flag	Short	Description	Default
`--manifest-file-path`	`-m`	Path to the manifest	`./txtx.yml`
`--output-json`	-	Output in JSON format; optionally provide a directory to write to file	-
`--output`	-	Pick specific output to stdout (conflicts with `--output-json`)	-
`--explain`	-	Explain how the runbook will be executed	`false`
`--port`	`-p`	Web UI port	`8488`
`--ip`	`-i`	Web UI IP address	`127.0.0.1`
`--env`	-	Environment to use from `txtx.yml` config	-
`--input`	-	Inputs for batch processing (repeatable)	-
`--force`	`-f`	Execute even if cached state shows already executed	`false`
`--log-level`	`-l`	Log level: `trace`, `debug`, `info`, `warn`, `error`	`info`
`--log-path`	-	Directory for runbook logs	`.surfpool/logs`

Supervised Mode

By default, surfpool run starts a web server for manual interaction with your Runbook execution steps. Each step can be validated, and runtime data can be input during execution.

surfpool run my-runbook

→ Processing manifest './txtx.yml'
✓ Runbook 'My Runbook' successfully checked and loaded

→ Running Web console
http://127.0.0.1:8488

Unsupervised Mode

In unsupervised mode, each Runbook step executes automatically in order. This is what Surfpool uses by default when deploying programs to your Surfnet.

surfpool run my-runbook -u

→ Processing manifest './txtx.yml'
✓ Runbook 'My Runbook' successfully checked and loaded

→ Starting runbook 'My Runbook' execution in unsupervised mode
┌───────┬───┐
│ ouput │ 1 │
└───────┴───┘

surfpool ls

Lists all runbooks declared in the manifest in the current directory.

surfpool ls [OPTIONS]

Flag	Short	Description	Default
`--manifest-file-path`	`-m`	Path to the manifest	`./txtx.yml`

surfpool cloud

Commands for interacting with the Txtx Cloud platform.

Authenticate with Txtx Cloud.

surfpool cloud login

surfpool cloud start

Start a new Cloud Surfnet instance.

surfpool cloud start [OPTIONS]

Flag	Short	Description	Default
`--workspace`	`-w`	Workspace name	-
`--name`	`-n`	Name of the surfnet to create	-
`--description`	`-d`	Description for the surfnet	-
`--rpc-url`	`-u`	Datasource RPC URL	`https://api.mainnet-beta.solana.com`
`--block-production`	`-b`	Block production mode: `clock`, `transaction`, or `manual`	-
`--profile-transactions`	-	Enable transaction profiling	`false`

surfpool completions

Generate shell completion scripts.

surfpool completions <SHELL>

Argument	Description
`SHELL`	Target shell (e.g., `bash`, `zsh`, `fish`)

surfpool mcp

Start an MCP (Model Context Protocol) server for AI tool integration.

surfpool mcp

CLI Commands