Comandos CLI

A CLI surfpool inicia Surfnets locais, executa Runbooks, lista Runbooks de um manifesto de workspace, gera completions de shell e inicia o servidor MCP do Surfpool.

Comandos

Comando	Descrição
`surfpool start`	Iniciar uma Surfnet local. Alias: `surfpool simnet`
`surfpool run`	Executar um Runbook
`surfpool ls`	Listar Runbooks no workspace atual
`surfpool completions`	Gerar scripts de completion de shell
`surfpool mcp`	Iniciar o servidor MCP do Surfpool

`surfpool start`

Inicia uma Surfnet local. Se executado em um diretório de programa Solana, o Surfpool pode gerar e executar Runbooks que fazem o deploy dos seus programas.

surfpool start [OPTIONS]

Rede & Portas

Flag	Short	Tipo	Padrão	Descrição
`--port <PORT>`	`-p`	inteiro	`8899`	Vincular o servidor JSON-RPC a esta porta.
`--ws-port <PORT>`	`-w`	inteiro	`8900`	Vincular o servidor WebSocket a esta porta.
`--host <HOST>`	`-o`	string	`127.0.0.1`	Vincular os serviços de RPC, WebSocket e Studio a este host.
`--rpc-url <RPC_URL>`	`-u`	string	nenhum	Realizar fork a partir desta URL de RPC de datasource. Conflita com `--network`. Também pode ser definido com `SURFPOOL_DATASOURCE_RPC_URL`.
`--network <NETWORK>`	`-n`	enum	nenhum	Realizar fork a partir de uma rede Solana predefinida. Valores: `mainnet`, `devnet`, `testnet`. Conflita com `--rpc-url`.
`--offline`	nenhum	booleano	`false`	Executar sem uma fonte de dados RPC remota.

Projeto & Implantação

Flag	Short	Type	Default	Description
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Caminho para o manifesto do runbook.
`--no-deploy`	none	boolean	`false`	Desativar implantações automáticas de programas.
`--runbook <RUNBOOK>`	`-r`	string[]	`deployment`	ID do runbook a executar após a inicialização. Repetível.
`--runbook-input <INPUT_PATH>`	`-i`	path[]	none	Arquivo de entrada a fornecer à execução do runbook. Repetível.
`--yes`	`-y`	boolean	`false`	Ignorar prompts de geração do runbook.
`--watch`	none	boolean	`false`	Reimplantar quando os artefatos do programa forem alterados.
`--artifacts-path <ARTIFACTS_PATH>`	none	path	none	Diretório contendo os artefatos do programa `.so`. Usa `target/deploy` como padrão quando omitido.
`--legacy-anchor-compatibility`	none	boolean	`false`	Usar padrões adequados para suites de teste legadas do Anchor.
`--anchor-test-config-path <TEST_TOML>`	none	path[]	none	Arquivo `Test.toml` do Anchor a inspecionar. Repetível.

Contas & Estado

Flag	Short	Type	Default	Description
`--airdrop <PUBKEY>`	`-a`	pubkey[]	none	pubkey para airdrop de SOL na inicialização. Repetível.
`--airdrop-keypair-path <KEYPAIR_PATH>`	`-k`	path[]	`~/.config/solana/id.json`	Caminho do keypair cujo pubkey deve receber um airdrop. Repetível.
`--airdrop-amount <LAMPORTS>`	`-q`	integer	`10000000000000`	lamports para airdrop em cada conta na inicialização.
`--snapshot <SNAPSHOT_PATH>`	none	path[]	none	Snapshot de conta JSON a pré-carregar. Repetível. Arquivos posteriores substituem arquivos anteriores em caso de chaves duplicadas.
`--db <DB_URL>`	none	string	none	URL de conexão de banco de dados para o estado persistente do Surfnet. Use `:memory:` para SQLite em memória, um arquivo `.sqlite` para SQLite em disco, ou uma URL do PostgreSQL quando compilado com a feature `postgres`.
`--surfnet-id <SURFNET_ID>`	none	string	`default`	Namespace de armazenamento para esta instância do Surfnet.

Runtime & UI

Flag	Short	Type	Default	Descrição
`--no-tui`	none	boolean	`false`	Exibir logs em vez de iniciar a interface de terminal.
`--no-studio`	none	boolean	`false`	Desativar o Surfpool Studio.
`--studio-port <PORT>`	`-s`	integer	`18488`	Vincular o Studio a esta porta.
`--daemon`	none	boolean	`false`	Executar o Surfpool como processo em segundo plano. O modo daemon é exclusivo para Linux.
`--ci`	none	boolean	`false`	Usar configurações adequadas para CI. Isso desativa a TUI, o Studio, o profiling de instruções e a saída de logs.

Comportamento do SVM

Flag	Short	Type	Default	Descrição
`--slot-time <MILLISECONDS>`	`-t`	integer	`400`	Tempo de slot em milissegundos.
`--block-production-mode <MODE>`	`-b`	enum	`clock`	Modo de produção de blocos.
`--feature <FEATURE_PUBKEY>`	`-f`	pubkey[]	none	Ativar uma funcionalidade do SVM por pubkey. Repetível. Nomes de funcionalidades estão obsoletos, mas ainda são aceitos para nomes anteriormente suportados.
`--disable-feature <FEATURE_PUBKEY>`	none	pubkey[]	none	Desativar uma funcionalidade do SVM por pubkey. Repetível. Nomes de funcionalidades estão obsoletos, mas ainda são aceitos para nomes anteriormente suportados.
`--features-all`	none	boolean	`false`	Ativar todas as funcionalidades do SVM a partir de `agave-feature-set`.
`--skip-signature-verification`	none	boolean	`false`	Ignorar a verificação de assinatura de transações.
`--skip-blockhash-check`	none	boolean	`false`	Ignorar a validação de blockhash de transações.

Observabilidade & Desempenho

Flag	Short	Type	Default	Description
`--geyser-plugin-config <PLUGIN_CONFIG_PATH>`	`-g`	path[]	none	Arquivo de configuração do plugin Geyser a carregar. Repetível.
`--disable-instruction-profiling`	none	boolean	`false`	Desativar o profiling de instruções.
`--max-profiles <COUNT>`	`-c`	integer	`200`	Perfis de transação a reter em memória. Valores mais altos aumentam o uso de memória.
`--log-bytes-limit <BYTES>`	none	integer	`10000`	Máximo de bytes armazenados para cada log de transação. Defina como `0` para logs ilimitados.
`--log-level <LEVEL>`	`-l`	enum	`info`	Nível de log do Simnet. Valores: `trace`, `debug`, `info`, `warn`, `error`, `none`.
`--log-path <LOG_DIR>`	none	path	`.surfpool/logs`	Diretório para logs do Simnet.
`--metrics-enabled`	none	boolean	env: `SURFPOOL_METRICS_ENABLED`	Ativar o endpoint de métricas do Prometheus. Disponível quando o Surfpool é compilado com o recurso `prometheus`.
`--metrics-addr <METRICS_ADDR>`	none	string	`127.0.0.1:9000`	Endereço do endpoint de métricas do Prometheus. Também pode ser definido com `SURFPOOL_METRICS_ADDR`. Disponível quando o Surfpool é compilado com o recurso `prometheus`.

Compatibilidade Obsoleta

Flag	Short	Type	Default	Description
`--subgraph-db <SUBGRAPH_DB>`	`-d`	string	`:memory:`	Obsoleto e oculto de `surfpool start --help`. Scripts existentes ainda podem passá-lo por compatibilidade.

Exemplos

Iniciar com configurações padrão:

surfpool start

Bifurcar devnet:

surfpool start --network devnet

Usar uma URL RPC de fonte de dados personalizada:

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

Imprimir logs em vez de iniciar o TUI:

surfpool start --no-tui

Iniciar sem uma fonte de dados RPC remota:

surfpool start --offline

Airdrop de SOL para múltiplas contas:

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

Carregar estado de conta a partir de snapshots:

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

Reimplantar programas quando target/deploy for alterado:

surfpool start --watch

Persistir o estado do Surfnet numa base de dados SQLite em disco:

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

`surfpool run`

Executa um Runbook. Pode executar um ficheiro .tx diretamente ou referenciar um Runbook declarado num manifesto txtx.yml.

surfpool run [OPTIONS] <RUNBOOK>

Argumentos

Argumento	Tipo	Descrição
`<RUNBOOK>`	string	ID do Runbook de `txtx.yml`, ou caminho para um ficheiro `.tx`.

Projeto

Flag	Abrev.	Tipo	Padrão	Descrição
`--manifest-file-path <MANIFEST_PATH>`	`-m`	caminho	`./txtx.yml`	Caminho para o manifesto do runbook.
`--env <ENVIRONMENT>`	none	string	none	Ambiente de `txtx.yml` a utilizar.

Modo de Execução

Estas flags são mutuamente exclusivas. Se nenhuma for especificada, o Surfpool utiliza a supervisão do browser.

Flag	Abrev.	Tipo	Padrão	Descrição
`--unsupervised`	`-u`	boolean	`false`	Executar sem a interface de supervisão.
`--browser`	`-b`	boolean	modo padrão	Executar com supervisão na interface do browser.
`--terminal`	`-t`	boolean	`false`	Executar com supervisão na consola do terminal.

Entradas & Saídas

Flag	Short	Tipo	Padrão	Descrição
`--output-json [<OUTPUT_DIR>]`	nenhum	caminho opcional	nenhum	Imprimir ou gravar saídas do Runbook em JSON. Quando um diretório é fornecido, a saída é gravada em um arquivo nesse diretório.
`--output <OUTPUT_NAME>`	nenhum	string	nenhum	Imprimir uma saída nomeada ao final da execução. Conflita com `--output-json`.
`--input <INPUT_PATH>`	nenhum	path[]	nenhum	Arquivo de entrada para processamento em lote. Repetível.

Execução

Flag	Short	Tipo	Padrão	Descrição
`--explain`	nenhum	booleano	`false`	Explicar como o Runbook será executado.
`--force`	`-f`	booleano	`false`	Ignorar estado de execução em cache.

Interface do Supervisor

Essas flags estão disponíveis quando o Surfpool é compilado com o recurso supervisor_ui.

Flag	Short	Tipo	Padrão	Descrição
`--port <PORT>`	`-p`	inteiro	`8488`	Porta da interface Web.
`--ip <IP_ADDRESS>`	`-i`	string	`127.0.0.1`	Endereço IP da interface Web.

Registro de Logs

Flag	Short	Tipo	Padrão	Descrição
`--log-level <LEVEL>`	`-l`	enum	`info`	Nível de log de execução do Runbook. Valores: `trace`, `debug`, `info`, `warn`, `error`.
`--log-path <LOG_DIR>`	nenhum	caminho	`.surfpool/logs`	Diretório para logs de execução do Runbook.

Exemplos

Execute um Runbook de manifesto com supervisão do navegador:

surfpool run deployment

Execute sem supervisão e grave saídas em JSON:

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

Execute um arquivo .tx diretamente:

surfpool run ./runbooks/deployment.tx

`surfpool ls`

Lista todos os Runbooks declarados no manifesto do workspace.

surfpool ls [OPTIONS]

Flag	Short	Type	Default	Description
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Caminho para o manifesto do runbook.

`surfpool completions`

Gera scripts de autocompletar para o shell.

surfpool completions <SHELL>

Argument	Type	Description
`<SHELL>`	enum	Shell para gerar autocompletar. Valores: `bash`, `elvish`, `fish`, `powershell`, `zsh`.

`surfpool mcp`

Inicia o servidor MCP do Surfpool para integração com ferramentas de IA.

surfpool mcp

Índice