Flags, exit codes and settings
The flags every pmo command accepts, what each exit code means, and the settings pmo reads.
These apply to every command in the 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.
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.