Scripting
--json, -y, non-interactive errors and exit codes for CI and agents
Every command is scriptable with two flags.
pier ls apps --json # machine output, never a prompt
pier deploy -y # skip the confirmation
pier rm app api -y # destructive verbs require -y non-interactivelyThe contract
-
A prompt opens only when stdin and stdout are terminals and
--jsonis not set. A JSON consumer never receives an interactive prompt. -
Otherwise the command fails with one shape:
output environment required in non-interactive mode — pass -e <slug>The hint names the flag or argument that supplies the missing value (
pass -e <slug>,pass <ref>,pass --yes). -
Every command that confirms takes
-y/--yes. Destructive verbs (rm,trash purge,--purge,--prune-external) refuse to run without it when there is no terminal. -
Abort (Esc, Ctrl-C) exits
130and printsCancelled.
JSON
--json (or -j) prints the same object the terminal view renders. Lists are
{"items": [...]}; single resources are flat objects; timestamps are RFC 3339 UTC; ids
are prefixed strings (app_…, pg_…).
pier info api --json | jq -r .url
pier deploys ls api --json | jq -r '.items[0].id'Exit codes
| Code | Meaning |
|---|---|
0 | success |
1 | the command ran and failed (the error text says why) |
2 | usage: unknown command or flag; a retired spelling prints try: pier … |
130 | cancelled |
Environment variables
| Variable | Effect |
|---|---|
PIER_PROFILE | session profile for this shell |
PIER_PROJECT | project override (name or id) |
NO_COLOR | disable colour |
PIER_NO_AGENT | never start the login helper |
In CI
curl -fsSL https://pier.run/install | sh
export PATH="$HOME/.local/bin:$PATH"
# a session token provisioned out of band; never commit it
pier login https://api.pier.run --no-browser
pier deploy -e prod -y --no-resume # --no-resume: fail rather than resume a paused target