Install Poolside Agent CLI - Poolside

Install the pool command to use Poolside from the terminal or in CI.

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.

Prerequisites

• On macOS or Linux, curl or wget, and tar
• BETA On Windows, PowerShell and tar

Install and Authenticate

Install

Run either command:

curl -fsSL https://downloads.poolside.ai/pool/install.sh | sh wget -qO- https://downloads.poolside.ai/pool/install.sh | sh

The installer asks you to accept the Poolside End User License Agreement. In headless environments, run export POOL_INSTALL_ACCEPT_EULA=1 before you run the installer. The script installs pool to ~/.local/bin by default unless POOL_INSTALL_DIR or XDG_BIN_HOME is set. If that directory is already on your PATH, the CLI is ready to use immediately. Otherwise, the installer either prompts to add it to your shell config or prints instructions to add it manually. You can rerun with POOL_INSTALL_UPDATE_PATH=1 to update your shell config automatically.

By default, the installer places pool.exe in %LOCALAPPDATA%\Programs\pool\bin unless POOL_INSTALL_DIR is set. It also adds the install directory to your user PATH. To skip the automatic PATH update, set POOL_INSTALL_UPDATE_PATH=0 before running the installer. In PowerShell, run:

irm https://downloads.poolside.ai/pool/install.ps1 | iex

The installer asks you to accept the Poolside End User License Agreement. In headless environments, set $env:POOL_INSTALL_ACCEPT_EULA = "1" in the same PowerShell session before you run the installer. Before you continue:

• If the installer indicates that the current session needs a PATH update, restart PowerShell or refresh PATH:

$env:Path = [System.Environment]::GetEnvironmentVariable('Path', 'User') + ';' + [System.Environment]::GetEnvironmentVariable('Path', 'Machine')

• If the installer says pool is not on your PATH, follow the printed instructions to add the install directory to PATH.

After PATH is refreshed, continue to authentication. If your shell does not resolve .exe commands, run the CLI as pool.exe instead of pool.

Log In

Choose the sign-in method that matches your setup. For help choosing a login option, see Log in to Poolside.

• Poolside deployment

pool login --api-url

• Poolside Platform

pool login

• OpenRouter

pool login

• OpenAI-compatible provider

pool login

Use this if your organization has a Poolside deployment. Replace <api-url> with the API URL for your Poolside deployment. Choose browser login or provide an API token. To sign in again later, run pool login.

Use this for the fastest way to get free developer access to models hosted by Poolside.

Choose Use Poolside Platform for free (recommended). This opens platform.poolside.ai in your browser. Copy the API key that Poolside creates for you, then paste it into the terminal.

Use this if you already use OpenRouter or need paid access to Poolside models.

Choose Use your OpenRouter account. Enter an OpenRouter API key from OpenRouter API keys.

Use this if you already have an API key for a model server or provider that exposes an OpenAI-compatible chat completions API.

Choose Connect an OpenAI-compatible provider. Enter the provider’s OpenAI-compatible API base URL and API key. If your server does not validate API keys, enter any non-empty value, such as local-test. If you run a local model server or use a provider that does not list models from its API, set the model name before starting pool:

POOLSIDE_STANDALONE_MODEL= pool

Verify

pool --version

Then choose the workflow you want to use:

• Work from the terminal
• Automate tasks
• Use Poolside in another ACP-compatible editor

For pool CLI bugs and feature requests, open an issue on GitHub.

Configure and Inspect Paths

Run pool config to see where the CLI stores configuration, credentials, logs, and trajectories. Run pool config settings to edit settings.yaml in your editor. After the editor exits, the CLI validates the file before saving it. By default, Poolside stores configuration files in ~/.config/poolside. This includes settings.yaml, which stores the saved API URL and other CLI settings, and credentials.json, where the CLI stores your saved auth token. If your environment uses a custom configuration directory, pool uses that location instead. Set POOLSIDE_API_URL to override the API URL saved in settings.yaml without changing the file.

CI and Automation

Use environment variables instead of stored credentials in non-interactive environments.

pool checks these before reading from configuration files. To run the CLI or call Poolside models in a GitHub Actions workflow, see Run Poolside in GitHub Actions. For authentication, pool checks in this order:

• When connected to a Poolside deployment: POOLSIDE_API_KEY, POOLSIDE_TOKEN, then credentials.json
• For Poolside Platform, OpenRouter, or OpenAI-compatible provider connections: POOLSIDE_API_KEY, then credentials.json

Uninstall Poolside Agent CLI

Use these steps to remove the pool command and, if needed, saved local configuration and state. If your environment uses custom configuration, log, or trajectory directories, run pool config before you start and note the paths.

1. To remove stored authentication credentials, log out:

    pool logout
   

   pool logout removes locally stored credentials. If you signed in to a Poolside deployment, it also revokes that credential on the deployment. If pool cannot reach the deployment, it removes the local credential anyway. If you signed in through Poolside Platform, OpenRouter, or an OpenAI-compatible provider, Poolside removes the credential only from your machine. To revoke those keys, use the provider’s console.

2. Remove the installed binary. By default, it is at ~/.local/bin/pool on macOS or Linux, or %LOCALAPPDATA%\Programs\pool\bin\pool.exe on Windows, unless POOL_INSTALL_DIR was set during installation. On macOS or Linux, XDG_BIN_HOME can also change the default location. To locate your copy, run command -v pool on macOS or Linux, or Get-Command pool on Windows. If the command reports a path, remove that file. If it reports an alias or function, remove the alias or function from your shell configuration or PowerShell profile. On macOS or Linux, if ls -l <path> shows the file is a symlink, remove its target too.

3. Remove saved local configuration (optional). Remove the config directory from the pool config output you noted earlier. If you did not note a custom config directory, remove the default config directory: ~/.config/poolside on macOS or Linux, or %USERPROFILE%\.config\poolside on Windows. This directory holds settings.yaml and credentials.json. To use the CLI again later, you may need to run pool login and recreate local settings.

4. If the installer added a PATH entry only for pool, remove that entry from your shell configuration or user PATH. Do not remove a shared directory such as ~/.local/bin from PATH if you use it for other tools.

5. Remove saved local state (optional). This includes logs, trajectories, session history, and other saved runtime state. It does not delete files from your projects. Remove the default directories for your platform:

   • macOS: ~/Library/Application Support/poolside
   • Linux: ~/.local/state/poolside and ~/.local/share/poolside
   • Windows: %LOCALAPPDATA%\poolside

On a custom setup, remove the poolside directories under the custom state or data locations you configured. The log and trajectory paths from pool config can help you identify the state directory.

If pool still runs after you remove the binary, you likely have another installation or a leftover shell alias. Run type pool on macOS or Linux, or Get-Command pool on Windows, to see what your shell is running.