> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> The paddock command-line tool: log in from your terminal, then create, list, read, and delete templates and agents, as tables or as JSON.

`paddock` is a single binary for macOS and Linux, on amd64 and arm64. It logs in through the console and saves an API key that the CLI and every server SDK find, and it creates, lists, reads, and deletes templates and agents. It calls only the public API, so anything it does your backend can do with a server SDK. It is built for people and for coding agents such as Claude Code and Codex: every command prints a table, or the API's own JSON with `--json`, and every error says what to fix.

## Install

```bash theme={null}
curl -fsSL https://api.paddock.build/install.sh | sh
```

The script detects your OS and architecture, downloads the latest release and its `SHA256SUMS`, checks the binary's SHA-256, and installs it as `paddock` only when the checksum matches, printing `Checksum verified`. It installs into `/usr/local/bin` when that is writable, else into `~/.local/bin`, and prints how to add the directory to your `PATH` when it is not on it.

| Variable | Meaning |
| - | - |
| `PADDOCK_INSTALL_DIR` | The directory to install into |
| `PADDOCK_VERSION` | A version to install instead of the latest |
| `PADDOCK_INSTALL_URL` | Where releases are served, default `https://api.paddock.build` |

`paddock version` prints the installed version.

## Log in

```bash theme={null}
$ paddock auth login
Open https://console.paddock.build/cli?code=WDJB-MJHT in your browser (opened for you).
Check that the page shows the code WDJB-MJHT, then confirm.
Waiting for approval…
Logged in to https://api.paddock.build/v1 with key cli-macbook (key_…3f9k2m7q).
Credentials saved to /Users/ada/.config/paddock/credentials.
```

`auth login` opens the console's approval page, which carries the code. Sign in, pick the organization, check that the page shows the same code, and confirm. The CLI then receives a new API key of that organization, named `cli-<hostname>`, checks that it works, and saves it. No secret is typed or pasted. The key is an ordinary API key: it is listed on the console's **API Keys** page with origin **CLI login**, and you revoke it there. If no browser opens, open the printed URL on any device. The code expires after 10 minutes; run `auth login` again then. `--base-url URL` logs in to another paddock API, given as its base URL ending in `/v1`.

| Command | Does |
| - | - |
| `paddock auth login [--base-url URL]` | Logs in and saves the key and the base URL to the credentials file, replacing it |
| `paddock auth status [--json]` | Prints the base URL and the key in use, the key masked, each with where it came from, and whether the API accepts the key. Exits 1 when no key is found or the API refuses it |
| `paddock auth logout` | Removes the credentials file. The key stays valid until you revoke it on **API Keys** |

## Credentials

`auth login` writes one JSON file with mode `0600`, in a directory of mode `0700`:

```text theme={null}
$XDG_CONFIG_HOME/paddock/credentials     # when XDG_CONFIG_HOME is set
~/.config/paddock/credentials            # otherwise, on macOS too
```

```json theme={null}
{ "apiKey": "pdk_sk_…", "baseUrl": "https://api.paddock.build/v1" }
```

The CLI and every server SDK look up the key and the base URL in the same order:

1. **API key**: an explicit option (in a server SDK), then `PADDOCK_API_KEY`, then the credentials file.
2. **Base URL**: an explicit option (`--base-url` on `auth login`, or the SDK's option), then `PADDOCK_BASE_URL`, then the credentials file, then `https://api.paddock.build/v1`.

The file's key and base URL were saved together, so they are used only together: a key from an option or `PADDOCK_API_KEY` never goes to the file's base URL, and the file's key is never sent to another base URL. The file is read only when no key comes from an option or the environment. A missing file means no credentials; a file that is needed but cannot be read fails with its path; run `paddock auth login` to replace it or `paddock auth logout` to remove it. See [Authentication](https://docs.paddock.build/platform/authentication.md#api-keys).

## Templates

```bash theme={null}
$ paddock templates create -f template.yaml --dry-run
dry run: template.yaml is valid and would be repo-explainer@1
$ paddock templates create -f template.yaml
TEMPLATE          HARNESS      MODEL          CREATED
repo-explainer@1  claude-code  claude-sonnet  2026-11-19 08:15:30
```

| Command | Does |
| - | - |
| `paddock templates create -f FILE [--dry-run] [--json]` | Sends the YAML file as it is and prints the created version. `--dry-run` runs every check, stores nothing, and prints the `name@version` a create would return |
| `paddock templates list [--json]` | Prints the latest version of every template |
| `paddock templates get NAME[@VERSION] [--json]` | Prints a version, the latest by default, then its document as YAML |
| `paddock templates delete NAME@VERSION` | Deletes one version. Fails with `409 conflict` while an agent uses it |
| `paddock templates delete NAME --all` | Deletes every version of a template, newest first, but only when no agent uses any; otherwise it deletes nothing and names each version in use and its agent count |

Tables name a template version by its ref, `name@version`, which is what `agents create --template` takes. Creating a document under an existing name adds that name's next version; a document identical to the latest version returns that version unchanged; and every version of a name runs on one harness, so a document with another harness is `409 conflict` with `details.reason` `harness_changed`. Agents keep the version they were created from. See [Templates](https://docs.paddock.build/guides/templates.md).

## Agents

```bash theme={null}
$ paddock agents create --template repo-explainer@1 --json | jq -r .id
agt_01jd7b3kq2v8w5x0m4n6p9r3t1
```

| Command | Does |
| - | - |
| `paddock agents create --template NAME@VERSION [--json]` | Creates an agent from a template version and prints it |
| `paddock agents list [--json]` | Prints every agent, newest first, with its template, status, and session count |
| `paddock agents get AGENT_ID [--json]` | Prints one agent |
| `paddock agents delete AGENT_ID` | Deletes an agent and its sandbox, and prints its ID |

Sessions and messages are not CLI commands: talk to an agent in the console's [Playground](https://docs.paddock.build/platform/console.md#playground), or with a server SDK. See [Agents and sessions](https://docs.paddock.build/guides/agents-and-sessions.md).

## JSON output

`--json` prints what the API returns: a template or an agent as the [API reference](https://docs.paddock.build/api-reference/introduction.md) documents it, a list as a JSON array of every item across every page, and `auth status` as `{ baseUrl, baseUrlSource, key, keySource, valid }` with the key masked. Flags may come before or after the arguments.

## Errors and exit codes

An API error goes to standard error as `error: <code>: <message>`, then each field error as `path (line N): message` (or just the message, for a problem with the whole document), then any other detail, then the request ID. A template validation error whose message is its first field error prints that error once:

```text theme={null}
error: invalid_request
  spec.model (line 7): model gpt-5.5 runs on codex, not claude-code
  request: req_01jd7b3kq2v8w5x0m4n6p9r3t1
```

With `--json`, the error is one line of the API's [error body](https://docs.paddock.build/platform/errors.md) with `requestId` added: `{"error":{"code":…,"message":…,"details":…,"requestId":…}}`.

| Exit code | Meaning |
| - | - |
| `0` | Success, or `--help` |
| `1` | Any failure: an API error, an unreadable file, no key |
| `2` | A usage error, such as `templates create` without `-f`, which prints the command's usage and flags; an unknown command prints `unknown command` and every command's usage |

`paddock --help` lists every command; `paddock <group> <command> --help`, such as `paddock templates create --help`, prints that command's usage and flags.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.