CLI reference - Poolside

Documentation Index

Fetch the complete documentation index at: /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.

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

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 other CLI authentication variables, see 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"

Exit codes

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.

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.

pool acp setup

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

pool acp logs

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

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.

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.

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.

Slash commands

Slash command availability depends on where you use pool.

Interactive slash commands

Use these commands in an interactive pool session.

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

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:

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.

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.

pool history sessions

pool history sessions lists recent sessions.

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

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.

pool secrets edit

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

pool secrets get

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

pool secrets delete

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