# Flags, exit codes and settings

> The flags every pmo command accepts, what each exit code means, and the settings pmo reads.

Source: https://docs.crossbot.io/pmo/cli/reference/global
Product: pmo · Kind: reference · Status: live · Last verified: 2026-10-21

These apply to every command in the [reference](/pmo/cli/reference).

## Flags every command accepts

| Flag | What it does |
| --- | --- |
| `--json` | Machine-readable output instead of text. Use it from scripts and AI sessions. |
| `--dry-run` | Runs every check and prints the change it would make, then writes nothing. |
| `--eng <engagement>` | Says which engagement an id belongs to, or narrows a query to one engagement. |
| `--if-match <digest>` | Writes only if the record has not changed since you read it. |
| `--as <kind>:<id>` | Names who is acting. With an installed `pmo` your sign-in or key already names you, so leave it out; naming somebody else is refused. |
| `--help`, `--version` | Prints the help, or the version. |

`pmo help <command>` prints any command's usage and an example. `pmo help filters` lists the filters every list command shares.

## Exit codes

Every command ends with one of these codes, so a script can tell what happened without reading the text.

| Code | Name | Meaning |
| --- | --- | --- |
| 0 | ok | It did the thing. |
| 1 | empty | The query matched nothing. Not an error: a loop over `pmo next` stops on it. |
| 2 | usage | Unknown command, bad flag, missing argument or malformed value. Nothing was sent or written. |
| 3 | not_found | No such engagement or task, or one you have not been given access to. |
| 4 | conflict | The record changed under you. Nothing was written; read it again and retry. |
| 5 | refused | A rule said no: wrong role, an unreadable title, a missing feature. The message says which. |
| 6 | read_only | Writing is switched off for this command line. |
| 7 | busy | The server was busy. Nothing was written, and it is safe to retry. |
| 8 | no_identity | Nobody is named: this computer is not signed in and has no key. |
| 9 | internal | `pmo` itself failed. Tell the PMO owner. |

## Settings

An installed `pmo` reads two settings, from your settings file or from the terminal window. The window wins over the file.

| Setting | What it holds |
| --- | --- |
| `PMO_API_URL` | The PMO server, for example `https://pmo.crossbot.io`. |
| `PMO_KEY` | A personal key, for AI sessions and scripts. Leave it empty to use your Cross account sign-in. A key always wins over a sign-in. |

Where the settings file lives on each computer, and the rules for keys, are in [Your key](/pmo/cli/keys#where-the-settings-file-lives).

<Callout title="The built-in help is behind on two points">
  `pmo --help` still describes `PMO_API_URL` as reserved and not implemented, and says every write needs `PMO_WRITES=1`. Both are out of date for the installed `pmo`: it always works through the server named by `PMO_API_URL`, and your sign-in or key is all a write needs.
</Callout>