Automate tasks - Poolside

Documentation Index

Fetch the complete documentation index at: /llms.txt

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

Run pool exec to send a single prompt and exit when the task is complete. Use this for scripts, CI pipelines, and one-off tasks where you don’t need a back-and-forth. For interactive work, see Work from the terminal instead.

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.

Basic usage

If you use pool exec in a non-interactive environment, set POOLSIDE_API_KEY before the command:

POOLSIDE_API_KEY=<api-key> pool exec -p "What does this codebase do?"

For other CLI authentication variables, see CI and automation. Pass a prompt inline:

pool exec -p "What does this codebase do?"

Read the prompt from a file:

pool exec -f prompt.txt

Pipe the prompt from standard input:

pool exec < prompt.txt

Use - to read from standard input when combining with other flags:

echo "Summarize this file" | pool exec -p -

Pass MCP server input variables

If an MCP server needs input from environment variables, start pool exec with those variables set:

KEY=VALUE pool exec -p "test"

Run in a specific directory

By default, pool exec uses your current directory. Use -d to point it somewhere else:

pool exec -p "Review this project" -d <project-path>

Continue from a previous run

Resume from the last run:

pool exec --continue -p "Now add tests for what you just wrote"

Resume a specific run by ID:

pool exec --continue=<run-id> -p "Now add tests for what you just wrote"

To find recent run IDs, use pool history logs.

Output format

By default, pool exec prints Markdown. Use -o json for newline-delimited JSON:

pool exec -p "List the exported functions in this file" -o json

JSON mode prints event-style records. Common types:

reasoning: Raw model reasoning
thought: Agent message text
toolCall: Tool invocations and arguments
toolCallResult: Tool results
oauth_url: Browser authentication required

Use JSON mode when another tool needs to consume the output.

Run without approval prompts

Use --unsafe-auto-allow when you want pool exec to run in automated mode without approval prompts:

pool exec -p "Review this repository for security issues" --unsafe-auto-allow

Use this only in trusted non-interactive environments. Explicit deny rules still apply. For persistent approval rules, path rules, and settings.yaml locations, see Permissions.

Override sandbox usage

Use --sandbox required to require a configured sandbox for the run:

pool exec -p "Review this repository" --sandbox required

Use --sandbox disabled only when you want to run without a configured sandbox.