--- title: CLI Commands description: Using the surfpool Command Line Interface (CLI) --- 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. ```sh surfpool start [OPTIONS] ``` ### Network & Ports | Flag | Short | Type | Default | Description | | --------------------- | ----- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | | `--port ` | `-p` | integer | `8899` | Bind the JSON-RPC server to this port. | | `--ws-port ` | `-w` | integer | `8900` | Bind the WebSocket server to this port. | | `--host ` | `-o` | string | `127.0.0.1` | Bind RPC, WebSocket, and Studio services to this host. | | `--rpc-url ` | `-u` | string | none | Fork from this datasource RPC URL. Conflicts with `--network`. Can also be set with `SURFPOOL_DATASOURCE_RPC_URL`. | | `--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 ` | `-m` | path | `./txtx.yml` | Path to the runbook manifest. | | `--no-deploy` | none | boolean | `false` | Disable automatic program deployments. | | `--runbook ` | `-r` | string[] | `deployment` | Runbook ID to execute after startup. Repeatable. | | `--runbook-input ` | `-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 ` | 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 ` | none | path[] | none | Anchor `Test.toml` file to inspect. Repeatable. | ### Accounts & State | Flag | Short | Type | Default | Description | | --------------------------------------- | ----- | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--airdrop ` | `-a` | pubkey[] | none | Pubkey to airdrop SOL to at startup. Repeatable. | | `--airdrop-keypair-path ` | `-k` | path[] | `~/.config/solana/id.json` | Keypair path whose pubkey should receive an airdrop. Repeatable. | | `--airdrop-amount ` | `-q` | integer | `10000000000000` | Lamports to airdrop to each startup account. | | `--snapshot ` | none | path[] | none | JSON account snapshot to preload. Repeatable. Later files override earlier files for duplicate keys. | | `--db ` | 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 ` | 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 ` | `-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 ` | `-t` | integer | `400` | Slot time in milliseconds. | | `--block-production-mode ` | `-b` | enum | `clock` | Block production mode. | | `--feature ` | `-f` | pubkey[] | none | Enable an SVM feature by pubkey. Repeatable. Feature names are deprecated but still accepted for previously supported names. | | `--disable-feature ` | 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 ` | `-g` | path[] | none | Geyser plugin config file to load. Repeatable. | | `--disable-instruction-profiling` | none | boolean | `false` | Disable instruction profiling. | | `--max-profiles ` | `-c` | integer | `200` | Transaction profiles to retain in memory. Higher values increase memory usage. | | `--log-bytes-limit ` | none | integer | `10000` | Maximum bytes stored for each transaction log. Set to `0` for unlimited logs. | | `--log-level ` | `-l` | enum | `info` | Simnet log level. Values: `trace`, `debug`, `info`, `warn`, `error`, `none`. | | `--log-path ` | 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 ` | 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 ` | `-d` | string | `:memory:` | Deprecated and hidden from `surfpool start --help`. Existing scripts can still pass it for compatibility. | ### Examples Start with default settings: ```sh surfpool start ``` Fork devnet: ```sh surfpool start --network devnet ``` Use a custom datasource RPC URL: ```sh surfpool start --rpc-url https://api.mainnet-beta.solana.com ``` Print logs instead of launching the TUI: ```sh surfpool start --no-tui ``` Start without a remote RPC datasource: ```sh surfpool start --offline ``` Airdrop SOL to multiple accounts: ```sh surfpool start --airdrop --airdrop ``` Load account state from snapshots: ```sh surfpool start --snapshot ./snapshot1.json --snapshot ./snapshot2.json ``` Redeploy programs when `target/deploy` changes: ```sh surfpool start --watch ``` Persist Surfnet state in an on-disk SQLite database: ```sh 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. ```sh surfpool run [OPTIONS] ``` ### Arguments | Argument | Type | Description | | ----------- | ------ | ---------------------------------------------------- | | `` | string | Runbook ID from `txtx.yml`, or path to a `.tx` file. | ### Project | Flag | Short | Type | Default | Description | | -------------------------------------- | ----- | ------ | ------------ | ----------------------------------- | | `--manifest-file-path ` | `-m` | path | `./txtx.yml` | Path to the runbook manifest. | | `--env ` | 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 []` | 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 ` | none | string | none | Print one named output at the end of execution. Conflicts with `--output-json`. | | `--input ` | 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 ` | `-p` | integer | `8488` | Web UI port. | | `--ip ` | `-i` | string | `127.0.0.1` | Web UI IP address. | ### Logging | Flag | Short | Type | Default | Description | | ---------------------- | ----- | ---- | ---------------- | ------------------------------------------------------------------------------- | | `--log-level ` | `-l` | enum | `info` | Runbook execution log level. Values: `trace`, `debug`, `info`, `warn`, `error`. | | `--log-path ` | none | path | `.surfpool/logs` | Directory for runbook execution logs. | ### Examples Run a manifest Runbook with browser supervision: ```sh surfpool run deployment ``` Run without supervision and write JSON outputs: ```sh surfpool run deployment --unsupervised --output-json .surfpool/runbook-outputs ``` Run a `.tx` file directly: ```sh surfpool run ./runbooks/deployment.tx ``` --- ## `surfpool ls` Lists all Runbooks declared in the workspace manifest. ```sh surfpool ls [OPTIONS] ``` | Flag | Short | Type | Default | Description | | -------------------------------------- | ----- | ---- | ------------ | ----------------------------- | | `--manifest-file-path ` | `-m` | path | `./txtx.yml` | Path to the runbook manifest. | --- ## `surfpool completions` Generates shell completion scripts. ```sh surfpool completions ``` | Argument | Type | Description | | --------- | ---- | ----------------------------------------------------------------------------------------- | | `` | enum | Shell to generate completions for. Values: `bash`, `elvish`, `fish`, `powershell`, `zsh`. | --- ## `surfpool mcp` Starts the Surfpool MCP server for AI tool integration. ```sh surfpool mcp ```