Comandos CLI

El CLI surfpool inicia Surfnets locales, ejecuta Runbooks, lista Runbooks desde un manifiesto de workspace, genera autocompletados de shell e inicia el servidor MCP de Surfpool.

Comandos

Comando	Descripción
`surfpool start`	Iniciar una Surfnet local. Alias: `surfpool simnet`
`surfpool run`	Ejecutar un Runbook
`surfpool ls`	Listar Runbooks en el workspace actual
`surfpool completions`	Generar scripts de autocompletado de shell
`surfpool mcp`	Iniciar el servidor MCP de Surfpool

`surfpool start`

Inicia una Surfnet local. Si lo ejecutas en un directorio de programa de Solana, Surfpool puede generar y ejecutar Runbooks que despliegan tus programas.

surfpool start [OPTIONS]

Red y puertos

Flag	Corto	Tipo	Predeterminado	Descripción
`--port <PORT>`	`-p`	entero	`8899`	Vincular el servidor JSON-RPC a este puerto.
`--ws-port <PORT>`	`-w`	entero	`8900`	Vincular el servidor WebSocket a este puerto.
`--host <HOST>`	`-o`	cadena	`127.0.0.1`	Vincular los servicios RPC, WebSocket y Studio a este host.
`--rpc-url <RPC_URL>`	`-u`	cadena	ninguno	Bifurcar desde esta URL RPC de fuente de datos. Conflicto con `--network`. También se puede establecer con `SURFPOOL_DATASOURCE_RPC_URL`.
`--network <NETWORK>`	`-n`	enum	ninguno	Bifurcar desde una red Solana predefinida. Valores: `mainnet`, `devnet`, `testnet`. Conflicto con `--rpc-url`.
`--offline`	ninguno	booleano	`false`	Ejecutar sin una fuente de datos RPC remota.

Proyecto e implementación

Flag	Short	Type	Default	Description
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Ruta al manifiesto del runbook.
`--no-deploy`	none	boolean	`false`	Deshabilitar las implementaciones automáticas de programas.
`--runbook <RUNBOOK>`	`-r`	string[]	`deployment`	ID del runbook a ejecutar tras el inicio. Repetible.
`--runbook-input <INPUT_PATH>`	`-i`	path[]	none	Archivo de entrada para la ejecución del runbook. Repetible.
`--yes`	`-y`	boolean	`false`	Omitir los mensajes de generación del runbook.
`--watch`	none	boolean	`false`	Volver a implementar cuando cambien los artefactos del programa.
`--artifacts-path <ARTIFACTS_PATH>`	none	path	none	Directorio que contiene los artefactos del programa `.so`. Por defecto es `target/deploy` si se omite.
`--legacy-anchor-compatibility`	none	boolean	`false`	Usar valores predeterminados adecuados para suites de prueba de Anchor heredadas.
`--anchor-test-config-path <TEST_TOML>`	none	path[]	none	Archivo `Test.toml` de Anchor a inspeccionar. Repetible.

Cuentas y estado

Flag	Short	Type	Default	Description
`--airdrop <PUBKEY>`	`-a`	pubkey[]	none	pubkey al que enviar SOL por airdrop al inicio. Repetible.
`--airdrop-keypair-path <KEYPAIR_PATH>`	`-k`	path[]	`~/.config/solana/id.json`	Ruta del keypair cuyo pubkey debe recibir un airdrop. Repetible.
`--airdrop-amount <LAMPORTS>`	`-q`	integer	`10000000000000`	lamports a enviar por airdrop a cada cuenta al inicio.
`--snapshot <SNAPSHOT_PATH>`	none	path[]	none	Instantánea de cuenta JSON a precargar. Repetible. Los archivos posteriores sobreescriben a los anteriores en caso de claves duplicadas.
`--db <DB_URL>`	none	string	none	URL de conexión a base de datos para el estado persistente de Surfnet. Use `:memory:` para SQLite en memoria, un archivo `.sqlite` para SQLite en disco, o una URL de PostgreSQL si se compiló con la función `postgres`.
`--surfnet-id <SURFNET_ID>`	none	string	`default`	Espacio de nombres de almacenamiento para esta instancia de Surfnet.

Tiempo de ejecución e interfaz de usuario

Flag	Short	Tipo	Predeterminado	Descripción
`--no-tui`	none	boolean	`false`	Imprime los registros en lugar de iniciar la interfaz de terminal.
`--no-studio`	none	boolean	`false`	Deshabilita Surfpool Studio.
`--studio-port <PORT>`	`-s`	integer	`18488`	Vincula Studio a este puerto.
`--daemon`	none	boolean	`false`	Ejecuta Surfpool como un proceso en segundo plano. El modo demonio solo está disponible en Linux.
`--ci`	none	boolean	`false`	Usa configuraciones adecuadas para CI. Esto deshabilita la TUI, Studio, el perfilado de instrucciones y la salida de registros.

Comportamiento de SVM

Flag	Short	Tipo	Predeterminado	Descripción
`--slot-time <MILLISECONDS>`	`-t`	integer	`400`	Tiempo de slot en milisegundos.
`--block-production-mode <MODE>`	`-b`	enum	`clock`	Modo de producción de bloques.
`--feature <FEATURE_PUBKEY>`	`-f`	pubkey[]	none	Habilita una función de SVM por pubkey. Repetible. Los nombres de función están obsoletos, pero aún se aceptan para los nombres previamente compatibles.
`--disable-feature <FEATURE_PUBKEY>`	none	pubkey[]	none	Deshabilita una función de SVM por pubkey. Repetible. Los nombres de función están obsoletos, pero aún se aceptan para los nombres previamente compatibles.
`--features-all`	none	boolean	`false`	Habilita todas las funciones de SVM desde `agave-feature-set`.
`--skip-signature-verification`	none	boolean	`false`	Omite la verificación de firma de transacciones.
`--skip-blockhash-check`	none	boolean	`false`	Omite la validación de blockhash de transacciones.

Observabilidad y rendimiento

Flag	Short	Type	Default	Description
`--geyser-plugin-config <PLUGIN_CONFIG_PATH>`	`-g`	path[]	none	Archivo de configuración del plugin Geyser a cargar. Repetible.
`--disable-instruction-profiling`	none	boolean	`false`	Deshabilitar la generación de perfiles de instrucciones.
`--max-profiles <COUNT>`	`-c`	integer	`200`	Perfiles de transacciones a retener en memoria. Los valores más altos aumentan el uso de memoria.
`--log-bytes-limit <BYTES>`	none	integer	`10000`	Máximo de bytes almacenados para cada registro de transacción. Establecer en `0` para registros ilimitados.
`--log-level <LEVEL>`	`-l`	enum	`info`	Nivel de log de simnet. Valores: `trace`, `debug`, `info`, `warn`, `error`, `none`.
`--log-path <LOG_DIR>`	none	path	`.surfpool/logs`	Directorio para los logs de simnet.
`--metrics-enabled`	none	boolean	env: `SURFPOOL_METRICS_ENABLED`	Habilitar el endpoint de métricas de Prometheus. Disponible cuando Surfpool se compila con la función `prometheus`.
`--metrics-addr <METRICS_ADDR>`	none	string	`127.0.0.1:9000`	Dirección del endpoint de métricas de Prometheus. También se puede configurar con `SURFPOOL_METRICS_ADDR`. Disponible cuando Surfpool se compila con la función `prometheus`.

Compatibilidad obsoleta

Flag	Short	Type	Default	Description
`--subgraph-db <SUBGRAPH_DB>`	`-d`	string	`:memory:`	Obsoleto y oculto en `surfpool start --help`. Los scripts existentes aún pueden utilizarlo por compatibilidad.

Ejemplos

Iniciar con la configuración predeterminada:

surfpool start

Bifurcar devnet:

surfpool start --network devnet

Usar una URL de RPC de fuente de datos personalizada:

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

Imprimir registros en lugar de iniciar la TUI:

surfpool start --no-tui

Iniciar sin una fuente de datos RPC remota:

surfpool start --offline

Airdrop de SOL a múltiples cuentas:

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

Cargar el estado de cuentas desde instantáneas:

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

Reimplementar programas cuando target/deploy cambia:

surfpool start --watch

Persistir el estado de Surfnet en una base de datos SQLite en disco:

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

`surfpool run`

Ejecuta un Runbook. Puedes ejecutar un archivo .tx directamente o hacer referencia a un Runbook declarado en un manifiesto txtx.yml.

surfpool run [OPTIONS] <RUNBOOK>

Argumentos

Argumento	Tipo	Descripción
`<RUNBOOK>`	string	ID del Runbook desde `txtx.yml`, o ruta a un archivo `.tx`.

Proyecto

Indicador	Corto	Tipo	Predeterminado	Descripción
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Ruta al manifiesto del runbook.
`--env <ENVIRONMENT>`	none	string	none	Entorno de `txtx.yml` a utilizar.

Modo de Ejecución

Estas opciones son mutuamente excluyentes. Si no se especifica ninguna, Surfpool utiliza la supervisión del navegador.

Indicador	Corto	Tipo	Predeterminado	Descripción
`--unsupervised`	`-u`	boolean	`false`	Ejecutar sin la interfaz de supervisión.
`--browser`	`-b`	boolean	modo predeterminado	Ejecutar con supervisión en la interfaz del navegador.
`--terminal`	`-t`	boolean	`false`	Ejecutar con supervisión en la consola de terminal.

Entradas y Salidas

Bandera	Corta	Tipo	Defecto	Descripción
`--output-json [<OUTPUT_DIR>]`	ninguna	ruta opcional	ninguna	Imprime o escribe las salidas del Runbook en formato JSON. Si se proporciona un directorio, la salida se escribe en un archivo dentro de ese directorio.
`--output <OUTPUT_NAME>`	ninguna	cadena	ninguna	Imprime una salida con nombre al final de la ejecución. Conflicto con `--output-json`.
`--input <INPUT_PATH>`	ninguna	ruta[]	ninguna	Archivo de entrada para procesamiento por lotes. Repetible.

Ejecución

Bandera	Corta	Tipo	Defecto	Descripción
`--explain`	ninguna	booleano	`false`	Explica cómo se ejecutará el Runbook.
`--force`	`-f`	booleano	`false`	Ignora el estado de ejecución en caché.

Interfaz de supervisor

Estas banderas están disponibles cuando Surfpool se compila con la función supervisor_ui.

Bandera	Corta	Tipo	Defecto	Descripción
`--port <PORT>`	`-p`	entero	`8488`	Puerto de la interfaz web.
`--ip <IP_ADDRESS>`	`-i`	cadena	`127.0.0.1`	Dirección IP de la interfaz web.

Registro

Bandera	Corta	Tipo	Defecto	Descripción
`--log-level <LEVEL>`	`-l`	enum	`info`	Nivel de registro de ejecución del Runbook. Valores: `trace`, `debug`, `info`, `warn`, `error`.
`--log-path <LOG_DIR>`	ninguna	ruta	`.surfpool/logs`	Directorio para los registros de ejecución del Runbook.

Ejemplos

Ejecutar un Runbook de manifiesto con supervisión del navegador:

surfpool run deployment

Ejecutar sin supervisión y escribir salidas JSON:

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

Ejecutar un archivo .tx directamente:

surfpool run ./runbooks/deployment.tx

`surfpool ls`

Lista todos los Runbooks declarados en el manifiesto del espacio de trabajo.

surfpool ls [OPTIONS]

Flag	Short	Type	Default	Description
`--manifest-file-path <MANIFEST_PATH>`	`-m`	path	`./txtx.yml`	Ruta al manifiesto del runbook.

`surfpool completions`

Genera scripts de autocompletado para la shell.

surfpool completions <SHELL>

Argument	Type	Description
`<SHELL>`	enum	Shell para la que se generarán los autocompletados. Valores: `bash`, `elvish`, `fish`, `powershell`, `zsh`.

`surfpool mcp`

Inicia el servidor MCP de Surfpool para la integración con herramientas de IA.

surfpool mcp

Tabla de Contenidos