CLI reference - Poolside

Reference for current pool commands, user-facing flags, slash commands, and exit codes. For an overview and usage guidance, start with Poolside Agent CLI.

This documentation describes Poolside Agent CLI v1.0.13. Check your version with pool --version. To update, exit any active session and run pool update from your terminal. See Poolside Agent CLI releases on GitHub for release history.

pool

pool starts an interactive session by default. Arguments after -- are forwarded to the configured agent server. By default, pool uses the credentials saved by pool login. To authenticate one invocation with an API key, set POOLSIDE_API_KEY before the command. To override the saved API URL for one invocation, set POOLSIDE_API_URL before pool.

POOLSIDE_API_KEY=<api-key> pool

If your MCP servers expect environment variables, start pool with those variables set.

KEY=VALUE pool

Flag	Short flag	Description
`--directory`	`-C`	Working directory for the interactive session
`--worktree [<branch-name>]`	`-w`	Run the session in a Git worktree for the named branch, creating the worktree and branch if needed. Use the flag without a branch name to generate a worktree name.
`--resume`	`-r`	Resume a previous session by ID, or use `-r` alone to open the session picker. In the picker, press `Tab` to switch between current-directory sessions and sessions from all directories.
`--model`	`-m`	Override the saved model preference for the interactive session
`--mode`		Override the saved mode preference for the interactive session
`--agent-server [<agent-server>]`	`-s`	Agent server entry, command, or remote ACP URL to use. Use `pool -s` to open the agent server picker.
`--sandbox <mode>`		Override sandbox usage for the Poolside agent server. Supported values: `required` and `disabled`.
`--prompt-queue <prompt>`	`-q`	Queue a prompt to send after the interactive session and agent connection finish initializing. Repeat to queue multiple prompts.
`--help`	`-h`	Show help for `pool` and exit
`--version`	`-v`	Show the current `pool` version and exit

Use pool <command> --help to show help for a subcommand. For keyboard shortcuts, see Work from the terminal.

pool exec

pool exec runs a single prompt non-interactively and then exits. Provide the prompt with --prompt, --prompt-file, or standard input. Files passed after -- are added as context for the run. To authenticate pool exec in a non-interactive environment, set POOLSIDE_API_KEY before the command. For complete setup examples, see Automate tasks.

POOLSIDE_API_KEY=<api-key> pool exec -p "test"

If your MCP servers expect environment variables, start pool exec with those variables set.

KEY=VALUE pool exec -p "test"

Flag	Short flag	Description
`--prompt`	`-p`	Prompt text. Use `-` to read the prompt from standard input.
`--prompt-file`	`-f`	File containing the prompt
`--directory`	`-d`	Working directory to operate in. Defaults to the current directory.
`--agent-name`	`-a`	Agent to use in tenant mode
`--api-url`		OpenAI-compatible API URL to use for provider connections
`--output`	`-o`	Output format: `markdown` or `json`. JSON output is newline-delimited JSON.
`--unsafe-auto-allow`		Automatically approve tool actions without confirmation
`--verbose`		Print verbose tool result output
`--sandbox <mode>`		Override sandbox usage. Supported values: `required` and `disabled`.
`--continue`		Continue a previous conversation. Provide a run ID, or use the flag alone to continue the last run.

Exit codes

Code	Meaning
`0`	Task completed successfully
`4`	The agent ran but reported that it could not complete the task
Other	Unexpected CLI or request error

pool acp

pool acp starts Poolside’s Agent Client Protocol (ACP) server over standard input and standard output. If your MCP servers expect environment variables, start pool acp with those variables set.

Flag	Short flag	Description
`--sandbox <mode>`		Override sandbox usage. Supported values: `required` and `disabled`.
`--settings <settings>`		Apply extra settings on top of workspace and global settings. Provide a path to a YAML settings file or inline YAML content.
`--version`	`-v`	Show the current `pool acp` version and exit

KEY=VALUE pool acp

Configure thought level through ACP session config options when your editor exposes them.

Available thought levels depend on your provider, agent server, and model.

Your ACP client might display generic effort values: default, max, xhigh (Extra high), high, medium, low, minimal, and none.
default clears your override and lets the backend choose an effort level.
When you configure thought level through an ACP client connected to Poolside Platform or an enterprise deployment with pool login, the backend determines how to apply the requested effort.
In those ACP sessions, use max to request thinking on and none to request thinking off. Other generic values do not select distinct reasoning levels.
With OpenRouter, available choices can come from provider model metadata.

pool acp serve

pool acp serve is experimental. Its flags and behavior can change in any release.

pool acp serve serves the Poolside ACP agent over a Streamable HTTP network transport on the configured listen address instead of standard input and output. One agent instance starts for each inbound connection. pool acp serve inherits the agent-configuration flags from pool acp, such as --sandbox and --settings.

pool acp serve --host 127.0.0.1 --port 3284

When you connect with pool --agent-server, use the /acp endpoint over Streamable HTTP. With the default host and port, the remote ACP URL is http://localhost:3284/acp.

Flag	Description
`--host <host>`	Host interface to bind. Defaults to `127.0.0.1`. Use `0.0.0.0` to accept connections from any interface.
`--port <port>`	TCP port to bind. Defaults to `3284`.
`--access-log <destination>`	HTTP access log destination. Supported values are `stderr`, `stdout`, `-`, `off`, or a file path. Defaults to `stderr`.

pool acp setup

Use pool acp setup to configure Zed or JetBrains to use Poolside.

Flag	Description
`--editor <editor>`	Editor to configure. Required. Supported values: `zed` and `jetbrains`

pool acp logs

pool acp logs reads ACP debug logs from the Poolside log directory for the current working directory.

Flag	Short flag	Description
`--follow`	`-f`	Follow log output
`--pretty`	`-p`	Pretty-print log output
`--session`		Show logs for a specific session ID

Setup and authentication

pool login runs the interactive login flow. Without flags, it asks whether you want to use Poolside Platform, your organization’s Poolside deployment, OpenRouter, or an OpenAI-compatible provider.

Flag	Description
`--api-key <key>`	Configure provider access with the given API key
`--api-url <url>`	Configure tenant mode with the given API URL

pool logout

pool logout removes stored credentials for the selected API URL. For Poolside deployment logins, it revokes the credential on the deployment and removes the local credential. If pool cannot reach the deployment, it removes the local credential anyway. For provider connections, it removes the stored API key from your machine.

Flag	Description
`--api-url <url>`	API URL to use

Configuration and updates

pool config

Prints the log, trajectory, and config directories, plus the credentials path.

pool config settings

Opens settings.yaml in VISUAL, EDITOR, or vi, validates it after you exit the editor, and then saves it. For approval rules, path rules, and sandbox configuration, see Permissions.

pool update

pool update [version] updates the CLI to the latest version, or to a specific version when you provide one.

Flag	Description
`--force`	Reinstall even if the CLI is already on the target version

Slash commands

Slash command availability depends on where you use pool.

Interactive slash commands

Use these commands in an interactive pool session.

Command	What it does
`/model`	Open the agent selector for the current session
`/mode`	Open the mode selector
`/thought-level [<level>]`	Open the thought-level selector, or set a thought level. Use `/effort` as an alias. Available only when the connected agent server provides thought-level choices.
`/new` or `/clear`	Clear conversation history and start a new session. The new session keeps the current model and mode unless you change them.
`/copy`	Copy the last agent response to the clipboard
`/rewind`	Roll back to a previous turn
`/resume`	Open the session picker and switch to a previous session
`/rename`	Rename the current session
`/move`	Move the session to another Git worktree, or create one. If the current worktree has uncommitted changes, choose whether to move those files too.
`/set-option <config-id> <value>`	Set a session configuration option by ID on the connected ACP agent
`/system`	Show the system prompt for the current session when available
`/feedback`	Open a feedback draft and optionally attach logs
`/logs`	Archive debug logs for the current session
`/quit` or `/exit`	Exit the session
`/debug:dump`	Write the raw agent-server message log to a local JSON file

When you use the Poolside agent server, these additional commands are available in interactive mode:

Command	What it does
`/plan`	Switch to plan mode
`/compact [<guidance>]`	Compact conversation context. Add guidance after the command to tell the agent what to preserve, such as `/compact preserve tool call errors`.
`/share`	Get a link to the trajectory viewer for the current session
`/mcp`	Show MCP servers, connection status, and tools for the current session
`/sandbox`	Show local sandbox configuration
`/sandbox-apply-to-host`	Review pending sandbox filesystem changes and apply them to the host workspace when available
`/skills`	Refresh and list available skills, including any skill load errors
`/usage`	Show token usage, context window state, and session cost when available

In interactive pool, skills use the $ skill picker instead of the slash-command menu. Type $ at the start of the prompt or after a space to open the skill picker and add a skill reference to your prompt.

ACP slash commands

When your editor passes slash commands to pool acp, these commands are available:

Command	What it does
`/plan`	Switch to plan mode when plan mode is available
`/clear`	Clear conversation history and free up context
`/compact [<guidance>]`	Compact conversation context. Add guidance after the command to tell the agent what to preserve, such as `/compact preserve tool call errors`.
`/share`	Get the trajectory viewer URL for the current session when trajectory sharing is available
`/rename`	Rename the current session
`/mcp`	Show MCP servers, connection status, and tools for the current session
`/sandbox`	Show local sandbox configuration
`/sandbox-apply-to-host`	Review pending sandbox filesystem changes and apply them to the host workspace when available
`/usage`	Show token usage, context window state, and session cost for the current session when available
`/skills`	Refresh and list available skills, including any skill load errors

Compatible ACP clients can expose available skills from pool acp as slash commands. The available skill commands depend on the skills configured for the agent and workspace.

History

pool history logs

Use pool history logs [<log-file-name-fragment>] to list recent log files or show one matching file.

Flag	Short flag	Description
`--all`	`-a`	Show all log files instead of the most recent 20
`--latest`	`-l`	Show the most recent log file and write its filename to standard error
`--pretty`	`-p`	Pretty-print log contents with colors and formatting
`--follow`	`-f`	Follow log output like `tail -f`

pool history trajectories

Use pool history trajectories [<trajectory-file-name-fragment>] to list recent trajectory files or show one matching file. Use --atif when you need to convert a local trajectory to Agent Trajectory Interchange Format (ATIF) JSON for external tooling.

Flag	Short flag	Description
`--all`	`-a`	Show all trajectory files instead of the most recent 20
`--latest`	`-l`	Show the most recent trajectory file
`--atif`		Render a single trajectory in ATIF JSON format. Use with `--latest` or part of a trajectory filename.
`--pretty`	`-p`	Pretty-print ATIF JSON. Only applies with `--atif`.

pool history sessions

pool history sessions lists recent sessions.

Flag	Short flag	Description
`--all`	`-a`	Show all sessions instead of the most recent 20

pool history sessions
pool history logs --latest --pretty
pool history trajectories --latest

MCP servers and secrets

pool mcp list

Lists configured MCP servers. Sensitive header values and environment values are masked in the output.

pool mcp get

Use pool mcp get <name> to inspect one MCP server configuration. Sensitive header values and environment values are masked in the output.

pool mcp remove

Use pool mcp remove <name> to remove an MCP server from settings.yaml.

pool mcp add

Use pool mcp add <name> [command] [args...] to add an MCP server. Use --transport to add a remote server. Without --transport, pool expects a command-based server and requires a command after --.

Flag	Short flag	Description
`--transport <type>`	`-t`	Transport type for remote servers: `http` or `sse`
`--env <key=value>`	`-e`	Environment variable to store with the server. Repeat as needed.
`--header <header>`	`-H`	HTTP header for HTTP or SSE transport. Repeat as needed.

Examples:

# Command-based server over stdio
pool mcp add filesystem -- node filesystem-server.js

# Remote HTTP server
pool mcp add --transport http notion https://mcp.notion.com/mcp

# Remote SSE server
pool mcp add --transport sse linear https://mcp.linear.app/sse

# Pass environment variables or HTTP headers
pool mcp add --env API_KEY=<api-key> myserver -- npx -y myserver-mcp
pool mcp add --transport http --header "Authorization: Bearer $TOKEN" svc https://example.com/mcp

# Inspect and remove
pool mcp list
pool mcp get <name>
pool mcp remove <name>

pool stores MCP server configuration under mcp_servers in settings.yaml. To share servers with a project, add them to .poolside/settings.yaml. To keep them personal across projects, add them to ~/.config/poolside/settings.yaml.

pool secrets list

Lists stored secrets and their source.

pool secrets add

Use pool secrets add <name> to store a secret in the system keychain.

Flag	Short flag	Description
`--description <text>`	`-d`	Description for the secret

pool secrets edit

Use pool secrets edit <name> to update a stored secret.

Flag	Short flag	Description
`--name <name>`		Rename the secret
`--description <text>`	`-d`	Update the description

pool secrets get

Use pool secrets get <name> to inspect a stored secret.

Flag	Description
`--show-value`	Show the stored secret value

pool secrets delete

Use pool secrets delete <name> to remove a secret from the keychain.

​pool

​pool exec

​Exit codes

​pool acp

​pool acp serve

​pool acp setup

​pool acp logs

​Setup and authentication

​pool login

​pool logout

​Configuration and updates

​pool config

​pool config settings

​pool update

​Slash commands

​Interactive slash commands

​ACP slash commands

​History

​pool history logs

​pool history trajectories

​pool history sessions

​MCP servers and secrets

​pool mcp list

​pool mcp get

​pool mcp remove

​pool mcp add

​pool secrets list

​pool secrets add

​pool secrets edit

​pool secrets get

​pool secrets delete

​Related resources

pool

pool exec

Exit codes

pool acp

pool acp serve

pool acp setup

pool acp logs

Setup and authentication

pool login

pool logout

Configuration and updates

pool config

pool config settings

pool update

Slash commands

Interactive slash commands

ACP slash commands

History

pool history logs

pool history trajectories

pool history sessions

MCP servers and secrets

pool mcp list

pool mcp get

pool mcp remove

pool mcp add

pool secrets list

pool secrets add

pool secrets edit

pool secrets get

pool secrets delete

Related resources