Reference for current pool shell commands, user-facing flags, and slash commands. This page omits hidden, development-only, and deprecated no-op flags. For workflow guidance, start with Poolside Agent CLI.
These docs describe Poolside Agent CLI v1.0.5. Run pool --version to check your installed version, run pool update to update the CLI, and see the 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.
If your MCP servers expect environment variables, start pool with those variables set.
| Flag | Short | Description |
|---|
--directory | -C | Working directory for the interactive session |
--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 [<name>] | -s | Agent server entry to use from pool.json. 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 |
pool <command> --help to show help for a subcommand.
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.
If your MCP servers expect environment variables, start pool exec with those variables set.
| Flag | Short | 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 in standalone mode |
--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. |
KEY=VALUE pool exec -p "test"
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 | Description |
|---|
--sandbox <mode> | | Override sandbox usage. Supported values: required and disabled. |
--version | -v | Show the current pool acp version and exit |
Use thought level control only with models behind OpenRouter or another provider that accepts the OpenRouter-style reasoning field. If the underlying model connects directly to the OpenAI Chat Completions API at https://api.openai.com/v1/chat/completions, requests that include the reasoning field fail because OpenAI rejects the field.For Claude 4.6 models through OpenRouter, effort settings other than none are ignored. OpenRouter uses adaptive thinking automatically for those requests.
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 | 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
pool login runs the interactive login flow. Without flags, it asks whether you want to authenticate to standalone Poolside or an existing Poolside tenant.
| Flag | Description |
|---|
--api-key <key> | Configure standalone mode 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. In standalone mode, it removes the stored standalone API key.
| 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 Tool 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 |
/new or /clear | Clear conversation history and start a new chat |
/copy | Copy the last assistant response to the clipboard |
/rewind | Roll back to a previous turn |
/rename | Rename the current session |
/feedback | Open a feedback draft and optionally attach logs |
/quit or /exit | Exit the session |
/debug:dump | Write the raw agent-server message log to a local JSON file |
| Command | What it does |
|---|
/plan | Switch to plan mode |
/compact | 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 |
/usage | Show token usage and context window state |
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 | 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 |
/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 for the current session |
/skills | Refresh and list available skills |
pool acp can also expose available skills 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 | 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 | 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 | 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 | 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. |
# 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 | Description |
|---|
--description <text> | -d | Description for the secret |
pool secrets edit
Use pool secrets edit <name> to update a stored secret.
| Flag | Short | 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.
