## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.poolside.ai/llms.txt)

Use this file to discover all available pages before exploring further.

Reference for current `pool` commands, user-facing flags, slash commands, and exit codes. For an overview and usage guidance, start with [Poolside Agent CLI](https://docs.poolside.ai/cli/pool).

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](https://github.com/poolsideai/pool/releases) 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](https://docs.poolside.ai/cli/interactive-mode#keyboard-shortcuts).

## 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 other CLI authentication variables, see [CI and automation](https://docs.poolside.ai/cli/install#ci-and-automation).

```
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

`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](https://docs.poolside.ai/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.