The pad command-line interface.
The pad CLI is the primary way to create and manage Pads.
macOS or Linux:
curl -fsSL https://pad.dev/install.sh | shWindows (PowerShell):
irm https://pad.dev/install.ps1 | iexUpdate an existing install with .
| Topic | Commands |
|---|---|
login, logout, whoami, profiles | |
up, create, start, stop, down, ls | |
ssh, exec | |
ports list, ports add, ports rm | |
secrets list, secrets set, secrets delete | |
connect, agents | |
init, validate, templates | |
upgrade, version |
These flags work on every command:
| Flag | Purpose |
|---|---|
--json | Output data as JSON (snake_case, mirrors the API). See . |
--profile <name> | Use a specific auth profile instead of the default. |
--api-url <url> | Override the Pad API URL. |
--auth-url <url> | Override the Pad auth server URL. |
--ssh-host <host[:port]> | Override the SSH gateway host. |
Most users only ever need --profile. The other flags target self-hosted or non-production environments.
Pass --json on any data-returning command to receive structured JSON instead of human-friendly tables. The output mirrors the : snake_case field names, TypeID identifiers (pad_…, org_…, tmpl_…), and the same list envelope.
pad ls --json | jq '.data[] | {alias, status}'
pad up --json | jq -r .id
pad whoami --json | jq -r .organization_idList responses always emit the envelope, even when empty:
{ "data": [], "next_page_url": null, "previous_page_url": null }Errors are written to stderr as a single line of JSON, with the process exiting 1:
{ "error": "not logged in: token expired" }For long-running commands like pad up and pad start, the streaming progress (status changes, setup logs) is suppressed when --json is set — only the final Pad object is emitted on success.
--json applies to commands that return data: ls, templates, whoami, profiles list, agents list, ports list, secrets list, ssh, and the resource-producing actions up, create, start, and ports add. Pure side-effect commands (down, stop, exec, logout, init, validate, upgrade, and the set/delete/remove variants) keep their human-readable output.
When you run pad inside a Pad, $PAD_ALIAS is set automatically. Commands like pad ssh, pad exec, and pad down default to the current Pad, so you can omit the alias.