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

# Automate with the CLI

> Use stable CLI output, exit codes, confirmations, and retries in automated workflows.

The CLI does not require interactive prompts. Every command works in a shell
script or CI job.

## Select an output mode

* `--json` and `-json` write one stable JSON document.
* `--jsonl` writes one object per line for list commands.
* `--quiet` writes identifiers only.
* stdout contains results only.
* stderr contains diagnostics, warnings, and request IDs.
* `NO_COLOR` disables color. The first release does not emit color.

List commands follow cursors automatically unless you pass `--after`.
`--limit` bounds the total item count. `--page-size` controls the API page
size.

Every JSON success contains `data` and `meta`. Metadata identifies the
`request_id`, `operation_id`, and generated or supplied `idempotency_key` when
they apply. For API commands, it also includes `http_status` and nullable
`retry_after` and `location` response-header values. Use `retry_after` to
schedule the next status check for accepted asynchronous work. JSON errors
contain `code`, `message`, `status`, `request_id`, `retryable`, and `details`.
A safety error can also contain `reason` and `retry_at`. Use `reason` to select
the correct recovery action. Wait until `retry_at` when it is present.

```bash theme={null}
openpmm posts list --workspace ws_01JABCDEF --json \
  | jq -r '.data[] | .id'

openpmm posts list --workspace ws_01JABCDEF --jsonl \
  | while read -r post; do
      printf '%s\n' "$post" | jq -r '.id'
    done
```

## Confirm risky actions

Publishing, retrying, disconnecting, and deleting require `--yes`. Without it,
the CLI exits with code `10` before it sends the mutation.

Conditional changes get the current ETag automatically. Use `--etag` to pin a
version that you reviewed earlier.

## Handle exit codes

| Code | Meaning                                                                |
| ---: | ---------------------------------------------------------------------- |
|  `0` | Success                                                                |
|  `1` | Unclassified CLI or remote failure                                     |
|  `2` | Invalid command, flag, or local input                                  |
|  `3` | Authentication failure                                                 |
|  `4` | Authorization or scope failure                                         |
|  `5` | Resource not found or inaccessible                                     |
|  `6` | Conflict, stale ETag, or invalid resource state                        |
|  `7` | Validation or provider preflight failure                               |
|  `8` | Rate limited or temporarily unavailable after safe retries             |
|  `9` | Ambiguous or partial external outcome that needs review                |
| `10` | Confirmation required                                                  |
| `11` | Publication needs action; structured output and receipts are preserved |

## Protect credentials and content

For a CLI-managed agent workflow, use only `openpmm` for OpenPMM operations.
Do not inspect the CLI credential store or call `/v1` with its key. Use request
files and `--json` for deterministic input and output.

If a repository already contains a custom OpenPMM HTTP client, do not connect
it to the CLI credential. Migrate the workflow to CLI request files. A direct
API integration must use a separate, least-privilege credential.

The CLI does not write API keys, provider tokens, signed media URLs, post copy,
cookies, or user email addresses to diagnostics or telemetry.

If an API key may be exposed, revoke it in the OpenPMM portal and replace it in
every automation. `openpmm auth logout` does not revoke the key.