Skip to main content
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

1

Install

Run either command:
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.
2

Log in

Choose the sign-in method that matches your setup. For help choosing a login option, see Log in to Poolside.
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.
3

Verify

Then choose the workflow you want to use:
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 Poolside deployment API URL saved in settings.yaml without changing the file. For direct provider connections, use POOLSIDE_STANDALONE_BASE_URL instead.

​
CI and automation

Use environment variables instead of stored credentials in non-interactive environments. pool checks these before reading from configuration files. When you set POOLSIDE_STANDALONE_BASE_URL for Poolside Platform, either https://inference.poolside.ai or https://inference.poolside.ai/v1 works. These docs use the shorter form. 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 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.