## 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](https://github.com/poolsideai/pool/releases) 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](https://docs.poolside.ai/get-started/log-in).

- Poolside deployment

pool login --api-url <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](https://openrouter.ai/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=<model-name> pool

### Verify
    pool --version

Then choose the workflow you want to use:

- [Work from the terminal](https://docs.poolside.ai/cli/interactive-mode)
- [Automate tasks](https://docs.poolside.ai/cli/automated-mode)
- [Use Poolside in another ACP-compatible editor](https://docs.poolside.ai/tools/other-acp)

For `pool` CLI bugs and feature requests, open an issue on [GitHub](https://github.com/poolsideai/pool).

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

| Variable | What it sets |
| --- | --- |
| `POOLSIDE_API_KEY` | Auth token for a Poolside deployment, Poolside Platform, OpenRouter, or an OpenAI-compatible provider |
| `POOLSIDE_TOKEN` | Alternative auth token for a Poolside deployment |
| `POOLSIDE_API_URL` | API URL, overrides the saved setting |
| `POOLSIDE_STANDALONE_BASE_URL` | OpenAI-compatible API base URL for provider connections |
| `POOLSIDE_STANDALONE_MODEL` | Model name for provider connections |

`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](https://docs.poolside.ai/tools/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.