JSON and scripting
--json output, exit codes, streaming with watch, and examples with jq.
Add --json to any command for machine-readable output. A command prints one JSON document on stdout; a stream (watch, logs) prints NDJSON, one JSON object per line.
airpost threads --role inbox -n 5 --json | jq -r '.threads[] | "\(.id)\t\(.subject)"'
Errors and exit codes
Errors go to stderr as one line of text starting airpost: , also with --json. Check the exit code rather than parsing stderr.
| Code | Meaning |
|---|---|
0 | OK |
1 | The command ran and failed (a failed send with --wait, a missing id, a draft validate error) |
2 | Usage error: bad flags or a combination that can’t be done |
3 | No engine running |
airpost status --json exits 3 when no engine is running but still prints its document, with engines empty and the installed services, so you can check both at once.
Commands that would ask for confirmation (account remove, account resync, folder empty) refuse to run with --json or without a terminal unless you pass -y/--yes.
Output shapes
Models are the engine’s JSON as stored, with every field. Field names follow the engine’s conventions: id, aid (account id), __cls (model class), v (version), timestamps in Unix seconds. The shapes below list the top-level keys. The command reference documents each command’s document in more detail, write commands included; inspect a real document with jq for the rest.
{"engines": [...], "services": [...], "skills": [...]}. Each engine has accounts (with accountId, email, state, connectionError and the account model), build and capabilities. Each service has name (engine, gateway, mcp-http), installed, running, pid, unit, bin, owner, url, port, onDemand and warnings.
{"accounts": [{"accountId", "email", "state", "error", "pid", "socket"}]}
{"threads": [...], "next": <cursor|null>, "more": <bool>}. Each thread has id, aid, subject, participants, unread, starred, attachmentCount, folders, labels and the lmt/lmrt/lmst last-message timestamps. next is set only when one account is listed; more says whether there are more either way.
{"threads": [...]}, threads as above.
{"folders": [...], "counts": {"<id>": {"total", "unread"}}} (or labels).
With a thread id: {"kind": "thread", "thread": {...}, "messages": [...]}, messages without bodies. With a message id: {"kind": "message", "message": {...}, "body", "files"}; body is filled with --body.
{"draft": {...}, "updated": <bool>}. updated is true when an existing draft was revised (--prefer-existing).
{"drafts": [...]}: message models with id, threadId, hMsgId (Message-ID), subject, from, to, cc, bcc, files, date.
{"scheduled": [...]}
archive, trash, move, mark-read and the rest print {"action", "dryRun", "accounts": [{"accountId", "email", "threadIds", "unchangedThreadIds"}], "taskIds", "undo"}. With --dry-run there is also threads. Pass undo to airpost undo <token>.
{"accounts": [{"accountId", "threadIds", "taskIds", "undo"}], "until"}
A bare array of task models (id, aid, __cls, status, …).
{"calendars": [...]}: calendar models as stored, each with the account’s email added.
{"occurrences": [...]}, with eventId, title, start/end (Unix seconds) or startDate/endDate for all-day events, organizer, attendees and myStatus.
{"contacts": [...]}; contact get prints {"contact", "metadata", "data"}.
{"text", "model", "cached", "usage"}; ai usage is a bare array of {"day", "provider", "feature", "inputTokens", "outputTokens", "requests"}.
{"messages": [...]} with opens and links per message; {"links": [{"url", "clickCount", "uniqueRecipients", ...}]}.
install prints the unit it wrote (service, installed, bin, sha256, path, text, …). start, stop, restart and uninstall print {"service", "name", "path", ...}.
{"entries": [...]}
{"values": {"<key>": <value>}}
{"rules": [...]}, {"templates": [{"id", "name", "subject", "variables", "preview"}]}, {"signatures": [...], "defaults": {"<address>": "<signature id>"}}.
Watch
airpost watch --json streams NDJSON until you interrupt it. Three kinds of line:
{"accountId":"54500b8c","seq":812,"modelClass":"Thread","type":"persist","modelJSONs":[{...}]}
{"event":"mail.new","accountId":"54500b8c","threadId":"...","messageId":"..."}
{"event":"disconnect","pid":51838,"reason":"..."}
- A delta has no
eventkey.typeispersist,unpersistormetadata-expiration, andmodelJSONsholds the changed models. mail.newis one message that landed unread in the inbox. It’s printed whatever--classsays.disconnectmeans an engine went away. The watch then exits 1, because a stream missing an account’s changes would look complete.
Limit deltas with -c/--class (repeatable), or print only new mail with --new-mail.
# Print the subject of each new message as it arrives
airpost watch --new-mail --json \
| jq --unbuffered -r 'select(.event == "mail.new") | .messageId' \
| while read -r id; do airpost show "$id" --json | jq -r '.message.subject'; done
Logs
airpost logs --json prints {"line": "..."} per log line, and keeps streaming with -f.
Examples
Archive newsletters older than a month, checking first:
airpost archive -q 'from:news@example.com before:30d' --dry-run --json | jq '.threads | length'
airpost archive -q 'from:news@example.com before:30d' --wait --json | jq -r '.undo'
Unread count per account:
airpost search 'is:unread in:inbox' -n 500 --json \
| jq -r '.threads | group_by(.aid)[] | "\(.[0].aid)\t\(length)"'
Write a reply from a file and send it, failing the script if it doesn’t go:
id=$(airpost draft reply "$THREAD_ID" --body-file reply.txt --json | jq -r '.draft.id')
airpost draft send "$id" --wait --timeout 120
Send tomorrow morning with a reminder:
airpost draft send "$id" --at 'tomorrow 9:00' --remind-in 3d
Wait for the engine before a script runs:
until airpost status --json >/dev/null 2>&1; do sleep 1; done
Fail a CI job when an account is stopped:
airpost status --json | jq -e '[.engines[].accounts[] | select(.state != "running")] | length == 0'
Export this week’s events as a TSV:
airpost calendar list --json \
| jq -r '.occurrences[] | [(.start // .startDate), .title, .eventId] | @tsv'
List the links clicked most this month:
airpost tracking links --since 30d --json | jq -r '.links[] | "\(.clickCount)\t\(.url)"'
Install a service plugin only if it’s exactly what you reviewed:
plan=$(airpost service install my-plugin --dry-run --json)
echo "$plan" | jq '{bin, sha256, unit: .unit.name}'
airpost service install my-plugin \
--expect-sha256 "$(echo "$plan" | jq -r .sha256)" \
--expect-plan "$(echo "$plan" | jq -r .planSha256)"
Call an engine method that has no command yet:
airpost rpc engine.status | jq .
Tips
- Use ids, not subjects, between steps. Every list prints them, and they stay stable while a subject can match several threads.
- Pass
--dry-runto thread actions in scripts first and check the count, as in the archive example above. - Use
--waiton sends and reprocess runs when the script’s next step depends on the server having the change; without it, commands return once the engine has queued the work. --jsonturns off prompts. Commands that would ask need--yes, so a script never hangs waiting for input.
Related: Command reference, CLI overview.