# Scripting

> --json, -y, non-interactive errors and exit codes for CI and agents

URL: https://pier.run/docs/cli/scripting

Every command is scriptable with two flags.

```bash
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-interactively
```

## The contract

* A prompt opens only when stdin **and** stdout are terminals and `--json` is not set. A
  JSON consumer never receives an interactive prompt.
* Otherwise the command fails with one shape:

  ```text title="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 `130` and prints `Cancelled`.

## 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_…`).

```bash
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

```bash
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
```