CLI overview
How the airpost command works: an engine client over a local socket, profiles, discovery, output and exit codes.
airpost is the command-line client for the Airpost mail engine. It reads, searches and drafts mail, sends drafts, archives, moves, labels and marks threads, manages folders, labels, rules, templates and signatures, and installs Airpost’s background services.
airpost status
airpost threads --role inbox -n 10
airpost search 'from:alice after:2w'
airpost show <thread-id>
airpost acts with your full rights on every account. The access levels and hidden accounts and folders in Preferences > MCP apply to airpost-mcp only. See Agents.
The mental model
airpost holds no mail and opens no database. Every command is a short-lived client of a running engine: it finds the engine through a discovery file, connects to its local socket, says hello (the engine answers with its pid, protocol version, features and the accounts it holds), sends one or more JSON-RPC requests, prints the result and exits. The desktop app, airpost-mcp and the web gateway talk to the same engine the same way, so a change you make from the shell shows in the Airpost window at once, and the other way round.
Changes to mail are queued as tasks in the engine. A command like airpost archive returns once the engine has applied the change locally and queued it for the server; add --wait to block until the server has it too. The engine keeps an undo log of these changes, which is what airpost undo reads.
Only airpost logs and the service commands (engine, gateway, mcp-http, service, skill, uninstall) work without a running engine.
How it finds the engine
When an engine starts it writes a discovery file into <profile>/run/ naming its pid and socket. A shared engine (the desktop’s, or airpost engine install’s) writes run/engine.json and lists the accounts it holds; per-account engines write one file each, with the account id.
airpost scans run/, skips files whose process is gone, connects to every live socket and builds its account list from the hello replies. engine.json is tried first, so a shared engine wins over per-account files left behind. Engines it can’t reach are reported on stderr as airpost: warning: skipped ... and the command carries on with the rest. If none answer, the command exits 3:
$ airpost threads
airpost: no engine running: start Airpost, or check --config-dir or AIRPOST_CONFIG_DIR (looked in /Users/you/Library/Application Support/Airpost/run)
An engine runs when:
- the desktop app is open (it starts its own), or
- you’ve installed the engine as a user unit with
airpost engine install, which keeps it running after the app quits and on machines with no desktop. See Background services and The engine.
The profile
The profile directory holds the accounts, the mail cache, the logs and the run/ directory. By default airpost uses the desktop app’s profile:
| OS | Default profile |
|---|---|
| macOS | ~/Library/Application Support/Airpost |
| Linux | $XDG_CONFIG_HOME/Airpost (default ~/.config/Airpost), then ~/snap/airpost/common for the snap |
When several candidates exist, airpost picks the first one with a live engine, else the first that exists. Use --config-dir or AIRPOST_CONFIG_DIR to point at another one, for example a second profile you run for testing:
export AIRPOST_CONFIG_DIR="$HOME/airpost-test"
airpost status
Choosing an account
Read commands (threads, search, folders, draft list, …) cover every account the running engines hold, and add an ACCOUNT column when there is more than one. Commands that act on ids (archive, show, draft send) find the account that owns each id, so you rarely need --account for them. Commands that create something in one place (draft new, label create, folder create, rules add, calendar create) need -a/--account when several accounts run; without it they exit 2:
$ airpost label create Receipts
airpost: several accounts are running (you@gmail.com, you@fastmail.com); pick one with --account
--account takes an account id or an email address, in any case.
Global flags
These work on every command.
| Flag | Description |
|---|---|
--config-dir <DIR> | The Airpost profile directory. Env: AIRPOST_CONFIG_DIR. |
-a, --account <ID|EMAIL> | The account to act on, by id or email address. Read commands without it cover every account. |
--json | Machine-readable output: one JSON document, or NDJSON for streams. See JSON and scripting. |
-h, --help | Help for the command. airpost <command> --help explains it in full. |
-V, --version | Print the version. |
Ids
Most commands take ids printed by other commands:
airpost threadsandairpost searchprint thread ids.airpost show <thread-id>prints message ids.airpost show <message-id>prints file (attachment) ids.airpost draft listprints draft ids.
--json prints every field, ids included.
Output
Human output goes to stdout as plain lines and tables. On a terminal, tables are fitted to its width (or COLUMNS when the terminal doesn’t report one) by shortening one column (the subject, in thread lists). Unread threads are bold, and problems such as a stopped account show in red. Color and bold are used only when stdout is a terminal and NO_COLOR is unset or empty. Piped output is never truncated and never styled.
There is no pager; pipe into less -R if you want one. A closed pipe (airpost threads | head) ends the command quietly with status 0.
Warnings go to stderr as airpost: warning: ...; errors as one line starting airpost: , also with --json.
With --json every command prints one compact JSON document on stdout, or NDJSON for the streams (watch, logs). See JSON and scripting.
Exit codes
| Code | Meaning |
|---|---|
0 | OK. Also --help, --version, and a closed output pipe. |
1 | The command ran and failed: a missing id, a failed task with --wait, a draft validate error, a timeout. |
2 | Usage: bad flags, or a request that can’t be done as given (several accounts and no --account, a confirmation needed without --yes). |
3 | No engine running, or no running engine holds the account you named. |