CLI 命令

surfpool CLI 可启动本地 Surfnet、执行 Runbook、从工作区清单中列出 Runbook、生成 Shell 补全脚本，以及启动 Surfpool MCP 服务器。

命令

命令	描述
`surfpool start`	启动本地 Surfnet。别名：`surfpool simnet`
`surfpool run`	执行 Runbook
`surfpool ls`	列出当前工作区中的 Runbook
`surfpool completions`	生成 Shell 补全脚本
`surfpool mcp`	启动 Surfpool MCP 服务器

`surfpool start`

启动本地 Surfnet。如果在 Solana 程序目录中运行，Surfpool 可自动生成并执行用于部署程序的 Runbook。

surfpool start [OPTIONS]

网络与端口

标志	简写	类型	默认值	描述
`--port <PORT>`	`-p`	整数	`8899`	将 JSON-RPC 服务器绑定到此端口。
`--ws-port <PORT>`	`-w`	整数	`8900`	将 WebSocket 服务器绑定到此端口。
`--host <HOST>`	`-o`	字符串	`127.0.0.1`	将 RPC、WebSocket 和 Studio 服务绑定到此主机。
`--rpc-url <RPC_URL>`	`-u`	字符串	无	从此数据源 RPC URL 进行分叉。与 `--network` 冲突。也可通过 `SURFPOOL_DATASOURCE_RPC_URL` 设置。
`--network <NETWORK>`	`-n`	枚举	无	从预定义的 Solana 网络进行分叉。可选值：`mainnet`、`devnet`、`testnet`。与 `--rpc-url` 冲突。
`--offline`	无	布尔值	`false`	在无远程 RPC 数据源的情况下运行。

项目与部署

Flag	Short	Type	Default	Description
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	运行手册清单的路径。
`--no-deploy`	none	boolean	`false`	禁用自动程序部署。
`--runbook <RUNBOOK>`	`-r`	string[]	`deployment`	启动后要执行的运行手册 ID，可重复指定。
`--runbook-input <INPUT_PATH>`	`-i`	path[]	none	提供给运行手册执行的输入文件，可重复指定。
`--yes`	`-y`	boolean	`false`	跳过运行手册生成提示。
`--watch`	none	boolean	`false`	当程序构件发生变化时重新部署。
`--artifacts-path <ARTIFACTS_PATH>`	none	path	none	包含 `.so` 程序构件的目录，省略时默认为 `target/deploy`。
`--legacy-anchor-compatibility`	none	boolean	`false`	使用适合旧版 Anchor 测试套件的默认设置。
`--anchor-test-config-path <TEST_TOML>`	none	path[]	none	要检查的 Anchor `Test.toml` 文件，可重复指定。

账户与状态

Flag	Short	Type	Default	Description
`--airdrop <PUBKEY>`	`-a`	pubkey[]	none	启动时空投 SOL 的目标 pubkey，可重复指定。
`--airdrop-keypair-path <KEYPAIR_PATH>`	`-k`	path[]	`~/.config/solana/id.json`	其 pubkey 应接收空投的 keypair 路径，可重复指定。
`--airdrop-amount <LAMPORTS>`	`-q`	integer	`10000000000000`	向每个启动账户空投的 lamport 数量。
`--snapshot <SNAPSHOT_PATH>`	none	path[]	none	预加载的 JSON 账户快照，可重复指定。后续文件中的重复键将覆盖之前文件中的内容。
`--db <DB_URL>`	none	string	none	用于持久化 Surfnet 状态的数据库连接 URL。使用 `:memory:` 表示内存 SQLite，使用 `.sqlite` 文件表示磁盘 SQLite，或在启用 `postgres` 特性时使用 PostgreSQL URL。
`--surfnet-id <SURFNET_ID>`	none	string	`default`	此 Surfnet 实例的存储命名空间。

运行时与界面

标志	简写	类型	默认值	描述
`--no-tui`	无	boolean	`false`	打印日志，而非启动终端界面。
`--no-studio`	无	boolean	`false`	禁用 Surfpool Studio。
`--studio-port <PORT>`	`-s`	integer	`18488`	将 Studio 绑定到此端口。
`--daemon`	无	boolean	`false`	以后台进程方式运行 Surfpool。守护进程模式仅支持 Linux。
`--ci`	无	boolean	`false`	使用适合 CI 的设置。此选项将禁用 TUI、Studio、指令性能分析及日志输出。

SVM 行为

标志	简写	类型	默认值	描述
`--slot-time <MILLISECONDS>`	`-t`	integer	`400`	slot 时间（毫秒）。
`--block-production-mode <MODE>`	`-b`	enum	`clock`	区块生产模式。
`--feature <FEATURE_PUBKEY>`	`-f`	pubkey[]	无	通过 pubkey 启用 SVM 功能。可重复使用。功能名称已弃用，但对之前支持的名称仍可接受。
`--disable-feature <FEATURE_PUBKEY>`	无	pubkey[]	无	通过 pubkey 禁用 SVM 功能。可重复使用。功能名称已弃用，但对之前支持的名称仍可接受。
`--features-all`	无	boolean	`false`	启用来自 `agave-feature-set` 的所有 SVM 功能。
`--skip-signature-verification`	无	boolean	`false`	跳过交易签名验证。
`--skip-blockhash-check`	无	boolean	`false`	跳过交易区块哈希验证。

可观测性与性能

标志	简写	类型	默认值	描述
`--geyser-plugin-config <PLUGIN_CONFIG_PATH>`	`-g`	path[]	无	要加载的 Geyser 插件配置文件，可重复使用。
`--disable-instruction-profiling`	无	boolean	`false`	禁用指令性能分析。
`--max-profiles <COUNT>`	`-c`	integer	`200`	保留在内存中的交易分析记录数，值越高内存占用越大。
`--log-bytes-limit <BYTES>`	无	integer	`10000`	每条交易日志存储的最大字节数。设置为 `0` 表示不限制日志大小。
`--log-level <LEVEL>`	`-l`	enum	`info`	模拟网络日志级别。可选值：`trace`、`debug`、`info`、`warn`、`error`、`none`。
`--log-path <LOG_DIR>`	无	path	`.surfpool/logs`	模拟网络日志目录。
`--metrics-enabled`	无	boolean	环境变量：`SURFPOOL_METRICS_ENABLED`	启用 Prometheus 指标端点。在使用 `prometheus` 特性构建 Surfpool 时可用。
`--metrics-addr <METRICS_ADDR>`	无	string	`127.0.0.1:9000`	Prometheus 指标端点地址，也可通过 `SURFPOOL_METRICS_ADDR` 设置。在使用 `prometheus` 特性构建 Surfpool 时可用。

已弃用的兼容性选项

标志	简写	类型	默认值	描述
`--subgraph-db <SUBGRAPH_DB>`	`-d`	string	`:memory:`	已弃用且在 `surfpool start --help` 中隐藏，现有脚本仍可传入此参数以保持兼容性。

示例

使用默认设置启动：

surfpool start

Fork devnet：

surfpool start --network devnet

使用自定义数据源 RPC URL：

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

打印日志而非启动 TUI：

surfpool start --no-tui

不使用远程 RPC 数据源启动：

surfpool start --offline

向多个账户空投 SOL：

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

从快照加载账户状态：

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

当 target/deploy 发生变化时重新部署程序：

surfpool start --watch

将 Surfnet 状态持久化到磁盘上的 SQLite 数据库：

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

`surfpool run`

执行一个 Runbook。您可以直接运行 .tx 文件，或引用在 txtx.yml 清单中声明的 Runbook。

surfpool run [OPTIONS] <RUNBOOK>

参数

参数	类型	描述
`<RUNBOOK>`	string	来自 `txtx.yml` 的 Runbook ID，或 `.tx` 文件的路径。

项目

标志	简写	类型	默认值	描述
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Runbook 清单的路径。
`--env <ENVIRONMENT>`	none	string	none	要使用的来自 `txtx.yml` 的环境。

执行模式

这些标志互斥。如果未指定任何标志，Surfpool 将使用浏览器监督模式。

标志	简写	类型	默认值	描述
`--unsupervised`	`-u`	boolean	`false`	在无监督 UI 模式下执行。
`--browser`	`-b`	boolean	default mode	在浏览器 UI 中以监督模式执行。
`--terminal`	`-t`	boolean	`false`	在终端控制台中以监督模式执行。

输入与输出

标志	简写	类型	默认值	描述
`--output-json [<OUTPUT_DIR>]`	无	可选路径	无	以 JSON 格式打印或写入 Runbook 输出。若提供目录，输出将写入该目录下的文件。
`--output <OUTPUT_NAME>`	无	字符串	无	在执行结束时打印一个指定的输出。与 `--output-json` 冲突。
`--input <INPUT_PATH>`	无	路径[]	无	用于批处理的输入文件。可重复使用。

执行

标志	简写	类型	默认值	描述
`--explain`	无	布尔值	`false`	说明 Runbook 的执行方式。
`--force`	`-f`	布尔值	`false`	忽略已缓存的执行状态。

管理界面

以下标志在 Surfpool 以 supervisor_ui 特性构建时可用。

标志	简写	类型	默认值	描述
`--port <PORT>`	`-p`	整数	`8488`	Web UI 端口。
`--ip <IP_ADDRESS>`	`-i`	字符串	`127.0.0.1`	Web UI IP 地址。

日志记录

标志	简写	类型	默认值	描述
`--log-level <LEVEL>`	`-l`	枚举	`info`	Runbook 执行日志级别。可选值：`trace`、`debug`、`info`、`warn`、`error`。
`--log-path <LOG_DIR>`	无	路径	`.surfpool/logs`	Runbook 执行日志目录。

示例

在浏览器监督下运行清单 Runbook：

surfpool run deployment

无监督运行并输出 JSON 结果：

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

直接运行 .tx 文件：

surfpool run ./runbooks/deployment.tx

`surfpool ls`

列出工作区清单中声明的所有 Runbook。

surfpool ls [OPTIONS]

标志	简写	类型	默认值	描述
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Runbook 清单的路径。

`surfpool completions`

生成 Shell 补全脚本。

surfpool completions <SHELL>

参数	类型	描述
`<SHELL>`	enum	要生成补全的 Shell。可选值：`bash`、`elvish`、`fish`、`powershell`、`zsh`。

`surfpool mcp`

启动 Surfpool MCP 服务器以集成 AI 工具。

surfpool mcp

Table of Contents