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

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. paddock version prints the installed version.

Log in

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.

Credentials

auth login writes one JSON file with mode 0600, in a directory of mode 0700:
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.

Templates

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.

Agents

Sessions and messages are not CLI commands: talk to an agent in the console’s Playground, or with a server SDK. See Agents and sessions.

JSON output

--json prints what the API returns: a template or an agent as the API reference 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:
With --json, the error is one line of the API’s error body with requestId added: {"error":{"code":…,"message":…,"details":…,"requestId":…}}. paddock --help lists every command; paddock <group> <command> --help, such as paddock templates create --help, prints that command’s usage and flags.