Documentation Index
Fetch the complete documentation index at: https://docs.poolside.ai/llms.txt
Use this file to discover all available pages before exploring further.
Reference for current pool commands and visible flags. For workflow guidance, start with Poolside Agent CLI.
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 |
--model | -m | Override the saved model preference for the interactive session |
--mode | | Override the saved mode preference for the interactive session |
--agent-server | -s | Agent server entry to use from pool.json |
--version | -v | Show the current pool version and exit |
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 to execute. Use - to read the prompt from standard input. |
--prompt-file | -f | File containing the prompt to execute |
--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 |
--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 |
|---|
--reasoning | | Set reasoning effort: xhigh, high, medium, low, minimal, or none. This sends the OpenRouter-style reasoning.effort field. |
--version | -v | Show the current pool acp version and exit |
Use reasoning 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 setup
pool setup runs the interactive setup flow.
- Without flags, it asks whether you want to authenticate to standalone Poolside or an existing Poolside tenant.
- With
--api-key, it configures standalone mode with the given API key.
- With
--api-url, it configures tenant mode and lets you choose browser login or direct token entry.
| 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 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 | Configure standalone mode with the given API key |
--api-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 | API URL to use |
Configuration and updates
pool config
Prints the log, trajectory, and config directories, plus the credentials file 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.
History
pool history logs
Use pool history logs [log-file-substring] 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-substring] to list recent trajectory files or show one matching file.
| Flag | Short | Description |
|---|
--all | -a | Show all trajectory files instead of the most recent 20 |
--latest | -l | Show the most recent trajectory file |
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.
