Skip to main content
Poolside Agent CLI (pool) is a cross-platform command-line interface for running Poolside agents and automating agentic workloads. When run without a subcommand, pool executes a prompt.

​
Installation

Prerequisites
  • Access to a Poolside instance URL. If you do not have an instance URL, contact your Poolside administrator.
  1. In your IDE Command Palette or search bar, type “Poolside”.
  2. Select Poolside: Install pool CLI.
  3. If prompted, enter your password.
After installation, you should see the confirmation message:poolside: Successfully installed pool CLI. You can now run pool in your terminal.This installs pool on your PATH and automatically configures your API URL and authorization token.

​
Configuration

pool uses a settings file and API credentials to connect to your Poolside instance.

​
Settings

Use the Poolside settings file (settings.yaml) to configure runtime settings such as api_url.

​
pool.api_url

Use pool.api_url to set the Poolside deployment URL that the pool command-line tool connects to. Define this setting in your personal default ~/.config/poolside/settings.yaml file: 
pool:
  api_url: https://poolside.example.com
If you install pool through Poolside Assistant, Poolside sets api_url automatically. You typically need to set api_url manually only when:
  • You installed pool outside the IDE
  • You are connecting to a different Poolside deployment
  • You are configuring pool in a remote or automated environment
pool reads the pool configuration only from your personal default ~/.config/poolside/settings.yaml file. It does not read pool.api_url from .poolside/settings.local.yaml or .poolside/settings.yaml.

​
Authentication

pool requires an API URL and token. It reads the API token from the first of the following sources that is defined:
  • $POOLSIDE_TOKEN (environment variable)
  • $XDG_CONFIG_HOME/poolside/credentials.json
    ($XDG_CONFIG_HOME defaults to ~/.config if unset)
If pool was not installed through an IDE extension, run: 
pool setup
This command configures pool interactively. To manage authentication manually, use the pool login and pool logout commands.

​
Credentials file

The credentials.json file stores API tokens used to communicate with the Poolside API. Example: 
jq . ~/.config/poolside/credentials.json

[
  {
    "type": "api-key",
    "apiUrl": "https://poolside.your-organization.com",
    "token": "ps-aaabbb..."
  }
]

​
File locations

By default, configuration files are stored in: 
~/.config/poolside
If your environment defines $XDG_CONFIG_HOME, pool follows the XDG Base Directory specification to determine configuration file locations. To print the active configuration directory: 
pool config

​
Using pool

​
Running tasks

Use pool to run single agentic tasks from the command line. Use --continue to resume a previous run. You can optionally provide a specific RunID. If no value is provided, pool continues the most recent run. pool is not an interactive terminal interface. For interactive workflows, use Poolside Assistant in your IDE. The CLI is designed for automated, headless execution, including:
  • Running in CI/CD pipelines
  • Automating software lifecycle tasks
  • Executing agentic workflows in production environments

​
Providing prompts

Provide prompts to pool using CLI arguments, files, or standard input redirection. Example: 
pool -p "analyze this patch for coding errors, and output PR comments \
following this JSON schema $(cat /tmp/schema.json). \
put the json array of comments within a pair of '<annotations>' xml tags" \
-- /tmp/diff.patch
Example output: 
<thought>
I'll analyze the provided patch file to identify any coding errors and
generate code review annotations. First, let me examine the contents of
the patch file to understand what changes have been made.
</thought>

<tool_call>
{"name": "read", "arguments": {"path": "/tmp/diff.patch"}}
</tool_call>

⏺ read(path:"/tmp/diff.patch")
...
<more agent actions>
...
<annotations>
  [{"level": "error", "message": "UDF function parse_diff_lines ..."}]
</annotations>
Other ways to supply prompts: 
# Via file
pool -f prompt.txt

# Via standard input redirection
pool < prompt.txt

# Via program arguments (use -- before filenames that should be treated as context)
pool -p "analyze these files" -- file1.go file2.go file3.go

# Compose with other CLI tools
find . -name '*.go' -not -name '*_test.go' | xargs \
  pool -p "check all of these files properly wrap errors with stack traces" --

​
Output formats

Use --output to control response format: 
pool -p "analyze these files" --output json -- file1.go
Supported formats:
  • markdown (default)
  • json (newline-delimited JSON, one object per line)

​
Automation mode

For automation use cases, rely on sandboxing or runtime resource limits instead of interactive approvals. If your administrator has granted you the required permission, you can use the --unsafe-auto-allow flag to allow the agent to execute tool calls without interactive confirmation: 
pool --unsafe-auto-allow=true -p "deploy to staging and run tests"
When this flag is enabled, tool calls run without approval prompts unless they match a deny rule in settings.yaml, which still blocks execution. For more information, see Tool permissions.
Use --unsafe-auto-allow only in trusted, sandboxed environments. Deny rules in settings.yaml still apply.

​
Exit codes

pool returns the following exit codes:
  • 0: Task success
  • 4: Task failure (task ran but could not complete)
  • Any other code: Unexpected error

​
Getting help

Use pool --help for comprehensive documentation. To view help for a specific command: 
pool [command] --help
Run pool help to see all available commands, including agent management, MCP configuration, login/logout, updates, and shell completion.

​
Debugging

To access trajectories, run: 
pool history
Trajectories include verbose agent actions and application logs generated by pool. If pool misbehaves at the application level, such as networking issues, review the logs. Use the request_id to cross-reference requests with Poolside API logs. For unexpected agent behavior, inspect trajectory output to understand the sequence of actions taken.

​
Conversion example

This example converts a set of JSON files into Go structs with go-playground/validator tags and generates unit tests for each type. 
pool -p "write a Go struct with github.com/go-playground/validator tags for each of \
these json files. Use the name of the file as struct name. \
Then write a unit test per type, with positive and negative examples" -- *.json