Command reference
Every airpost subcommand, argument and flag.
This page lists every airpost command by group: what it does, its synopsis, its flags, examples with the output you should expect, and the shape of its --json document. Sample output uses made-up ids and addresses; the layout and wording come from the binary.
Every command also takes the global flags: --config-dir, -a/--account, --json, -h and -V. airpost <command> --help prints the same information from the binary you have.
Times written WHEN take 30m, 2h, 3d, 1w, tomorrow (9:00), tomorrow 14:30, a date (9:00 that day), or an ISO 8601 date and time (2026-11-02T14:30, local unless it has an offset).
Status and sync
status
The running engines and the state of their accounts, plus the installed services (engine, gateway, mcp-http). Exits 3 when no engine is running, but still prints the services.
airpost status [-a ACCOUNT]
$ airpost status
ACCOUNT ID STATE SERVER PID UPTIME ENGINE
you@gmail.com 54500b8c running ok 51838 2h 14m 0.1.0
you@fastmail.com 9e01a7d2 running offline 51838 2h 14m 0.1.0
SERVICE STATE PID URL BINARY
engine running 51838 - /Applications/Airpost.app/Contents/MacOS/airpost-engine
gateway not installed - - -
mcp-http on demand - http://127.0.0.1:... /Users/you/.local/bin/airpost-mcp
STATE is starting, running, stopped or removed; a stopped account shows the error key that stopped it (stopped: ErrorAuthentication) in red. SERVER is offline while a running account can’t reach its server.
Related: accounts, logs, The engine.
accounts
The accounts the running engines hold: id, email, state, the engine’s pid and socket.
$ airpost accounts
EMAIL ID STATE PID
you@gmail.com 54500b8c running 51838
you@fastmail.com 9e01a7d2 running 51838
sync
Start a sync pass now, on every account or the one --account names. Stopped accounts are skipped with a note. It returns once the pass has started; it doesn’t wait for it to end.
$ airpost sync -a you@example.com
Syncing you@example.com
--json: {"accounts": ["<account id>", ...]}, the accounts it woke.
watch
Print deltas and new mail as the engines send them, until interrupted. With --json it streams NDJSON; see JSON and scripting.
| Flag | Description |
|---|---|
-c, --class <CLASS> | Only these model classes (Thread, Message, Folder, Task, …). New mail is printed either way. |
--new-mail | Only new mail: one line per message that lands unread in the inbox. |
Each line starts with the local time and the account. A delta line has the change type, the model class, how many models changed and a summary of the first:
$ airpost watch --new-mail
14:02:51 you@gmail.com new mail 8c1d2e4f thread 3a9f01b2
$ airpost watch -c Thread
14:03:10 you@gmail.com persist Thread 1 Lunch on Thursday?
It runs until you press Ctrl-C. If an engine goes away the watch exits 1, since the stream would otherwise miss that account’s changes.
logs
Print an account’s engine log, or a service’s. Needs no engine.
airpost logs [ACCOUNT|SERVICE]
| Argument / flag | Description |
|---|---|
ACCOUNT|SERVICE | Account id or email, or engine, gateway or mcp-http. Defaults to --account, else the only account with a log. |
-f, --follow | Keep printing lines as they are written, across log rotation. |
-n, --lines <LINES> | How many of the last lines to print first. Default 20. |
airpost logs you@gmail.com -n 100
airpost logs engine -f
With --json each line is {"line": "..."}. See Background services for where each log lives.
Accounts
account
Add, change, reorder, resync, sign in again to and remove accounts of the serve engine.
account add
airpost account add <EMAIL> [flags]
IMAP accounts (the default) get the servers Airpost finds for the address, changed by the flags below, and a password: asked for on a terminal, or one line on stdin with --password-stdin. Gmail, Office 365 and Outlook accounts sign in in the browser (on a server, with --paste). The engine tests the account before it keeps it.
| Flag | Description |
|---|---|
--provider <PROVIDER> | imap, gmail, office365, outlook, or a preset the servers come from (yahoo, icloud, fastmail, …). Default imap. |
--name <NAME> | Your name, as recipients see it. |
--imap-host <HOST> | IMAP server. |
--imap-port <PORT> | IMAP port. |
--imap-security <tls|starttls> | Airpost never sends a password unencrypted. |
--imap-username <USER> | IMAP username. |
--smtp-host <HOST> | SMTP server. |
--smtp-port <PORT> | SMTP port. |
--smtp-security <tls|starttls> | SMTP security. |
--smtp-username <USER> | SMTP username. |
--password-stdin | Read the password (IMAP and SMTP) from the first line of stdin. |
--shared-mailbox <EMAIL> | Office 365: open this shared mailbox with your own sign-in. |
--no-browser | Print the sign-in address instead of opening the browser. |
--paste | For a server without a browser: print the sign-in address, then read the address the browser ends on (http://127.0.0.1:<port>/?code=...) from stdin instead of listening for it. |
--port <PORT> | The port on 127.0.0.1 the browser’s sign-in comes back to. Default 12141. |
--timeout <TIMEOUT> | Seconds to wait for the sign-in. Default 300. |
printf '%s\n' "$PASSWORD" | airpost account add me@fastmail.com --provider fastmail --password-stdin
airpost account add me@gmail.com --provider gmail --paste
Related: account reauth, status.
account remove
Stop an account and remove it from the engine with its stored credentials (and a Google grant). The desktop window keeps listing it until it is removed there too.
| Argument / flag | Description |
|---|---|
ID|EMAIL | The account. |
--delete-data | Also delete its mail cache. Without it the cache stays for an account added again. |
-y, --yes | Don’t ask first. Needed without a terminal, and with --json. |
account update
Change how an account shows: its name, aliases and the alias new mail starts from.
| Argument / flag | Description |
|---|---|
ID|EMAIL | The account. |
--name <NAME> | Your name, as recipients see it. |
--alias <ALIAS> | Add an alias to send from: Name <address>, an address, or a name. Repeatable. |
--remove-alias <ALIAS> | Remove an alias, by its text or address. Repeatable. |
--default-alias <ALIAS|none> | The alias new mail starts from; none for the account’s own address. |
account reorder
airpost account reorder <ID|EMAIL>...
Put accounts in this order in the engine’s list. Accounts not named keep their order after these. The desktop window keeps its own order.
account resync
Delete an account’s mail cache and download its mail again, as Preferences > Accounts > Rebuild this account does.
| Argument / flag | Description |
|---|---|
ID|EMAIL | The account. |
-y, --yes | Don’t ask first. Needed without a terminal, and with --json. |
account reauth
Sign in to an account again: the browser for Gmail, Office 365 and Outlook, a new password for the others.
| Argument / flag | Description |
|---|---|
ID|EMAIL | The account. |
--password-stdin | Read the new password from the first line of stdin. |
--no-browser | Print the sign-in address instead of opening the browser. |
--paste | Read the address the browser ends on from stdin. |
--port <PORT> | Callback port on 127.0.0.1. Default 12141. |
--timeout <TIMEOUT> | Seconds to wait for the sign-in. Default 300. |
Reading mail
folders, labels
Folders (or labels) with unread and total thread counts.
airpost folders
airpost labels -a you@gmail.com
threads
Threads, newest first.
| Flag | Description |
|---|---|
--folder <FOLDER> | A folder, by path or id. |
--label <LABEL> | A label, by path or id. |
--role <ROLE> | A role: inbox, sent, drafts, trash, spam, archive, all, important, … |
-n, --limit <LIMIT> | How many threads (default 50; with --all, the page size). |
--all | Page through every thread. |
--before <CURSOR> | Continue after a page: the next of threads --json (one account only). |
$ airpost threads --role inbox -n 3 -a you@gmail.com
DATE FROM SUBJECT ID
09:41 Alice Chen * Q4 planning notes 3a9f01b2
Nov 14 Bob Smith Re: Lunch on Thursday? 77d0c3e9
Nov 12 GitHub [airpost] CI failed on main c24e8a10
Dates are the time for today, Mon DD for this year and YYYY-MM-DD before. A * marks a starred thread; unread threads are bold on a terminal. With several accounts there is an ACCOUNT column first.
Page through one account by hand:
next=$(airpost threads -a you@gmail.com --role all --json | jq -r .next)
airpost threads -a you@gmail.com --role all --before "$next"
search
airpost search <QUERY>...
Threads matching a query in the search bar’s grammar, newest first. Quote the whole query so the shell keeps its quotes and parentheses. There is no label:, cc:, -term or larger:; use in:<label> and NOT. See Search for the grammar.
| Flag | Description |
|---|---|
-n, --limit <LIMIT> | How many threads (default 50). |
airpost search 'from:alice "project alpha" after:2w'
airpost search 'is:unread in:inbox has:attachment' -n 20
airpost search '(from:bob OR from:carol) subject:invoice before:2026-10-01'
Output is the same table as threads. --json prints {"threads": [...]} with the same thread models.
Related: threads, show, and every thread action through --query.
show
airpost show <ID>
Given a thread id, the thread and its messages without bodies. Given a message id, the message and its attachments.
| Flag | Description |
|---|---|
--body | With a message id: include the body, downloading it first if needed. |
With a thread id:
$ airpost show 77d0c3e9
Subject: Re: Lunch on Thursday?
With: Bob Smith <bob@example.com>, you@gmail.com
In: INBOX
Thread: 77d0c3e9
DATE FROM SNIPPET MESSAGE ID
Nov 13 Bob Smith Are you free Thursday around noon? 5be1f0aa
Nov 14 You Thursday works. The usual place? e93c44d1
Nov 14 Bob Smith Perfect, see you there. 0f7a2c58
With a message id and --body:
$ airpost show 0f7a2c58 --body
Subject: Re: Lunch on Thursday?
From: Bob Smith <bob@example.com>
To: you@gmail.com
Date: 2026-11-14 10:22 CET
Folders: INBOX
Flags: unread
Files: menu.pdf (84 KB, id 2d6e9b03)
Thread: 77d0c3e9
Id: 0f7a2c58
Perfect, see you there.
Without --body the last part is the snippet, followed by (snippet; --body shows the whole message). A Warning: line appears when the engine flagged the message (for example a sender that doesn’t match its domain).
attachment
| Subcommand | Description |
|---|---|
attachment get <FILE_ID> | Save one attachment, downloading it if needed, and print its path. airpost show <message-id> lists file ids. |
attachment save <MESSAGE_ID> | Save every attachment of a message into a directory and print their paths. |
| Flag | Applies to | Description |
|---|---|---|
-o, --output <PATH> | get | Where to write it (default: its name in the current directory); - for stdout. |
--dir <DIR> | save | The directory (default: the current one); made if missing. |
--force | both | Replace files that exist. |
airpost attachment get 2d6e9b03 -o ~/Downloads/menu.pdf
airpost attachment get 2d6e9b03 -o - | pdftotext - -
airpost attachment save 0f7a2c58 --dir ./attachments
--json for get: {"accountId", "fileId", "filename", "contentType", "size", "path"}. For save: {"accountId", "messageId", "files": [...]}, one such object per file.
export
Save a message as an .eml file, or a folder as an mbox file (mboxrd), from the server’s copy.
airpost export <message-id> -o msg.eml
airpost export --mbox --folder INBOX -a me@example.com -o inbox.mbox
| Argument / flag | Description |
|---|---|
MESSAGE_ID | The message (airpost show <thread-id> lists them). |
--mbox | Export the folder --folder of the account as one mbox file. |
--folder <FOLDER> | With --mbox: the folder, by path, id or role. |
-o, --output <FILE> | Required. The file to write. |
--force | Replace the file if it exists. |
--timeout <SECS> | Give up after this many seconds (default 120 for a message, none for a folder). |
It prints the path written (and, for a folder, the message count: inbox.mbox (1243 messages)).
--json: for a message {"accountId", "messageId", "path", "size", "taskId"}; for --mbox {"accountId", "folder", "folderId", "path", "messages", "taskId"}.
Acting on threads
archive, trash, move, mark-read, mark-unread, star, unstar, spam, not-spam, label add and label remove all take thread ids from search or threads, in any account, or --query to act on every thread a search finds.
| Command | What it does |
|---|---|
archive [THREAD_ID]... | Archive: Gmail takes threads out of the inbox, other accounts move them to Archive (or All Mail). |
trash [THREAD_ID]... | Move to the trash. |
move <FOLDER> [THREAD_ID]... | Move to a folder, by path, id or role. On Gmail the target can be a label: the threads’ labels are replaced by it. |
mark-read, mark-unread | Mark read or unread. |
star, unstar | Star or unstar. |
spam | Move to Spam. |
not-spam | Move out of Spam: to the inbox, or All Mail on Gmail. Only the copies in Spam move. |
label add <LABEL> [THREAD_ID]... | Add an existing label (Gmail). |
label remove <LABEL> [THREAD_ID]... | Take a label off. |
Shared flags:
| Flag | Description |
|---|---|
-q, --query <QUERY> | Every thread matching this search, instead of ids. |
-n, --limit <LIMIT> | With --query: at most this many threads, newest first. Without it, a query matching more than 500 threads is refused. |
--dry-run | List the threads it takes and check the folder or label; change nothing. |
--wait | Wait until the change has reached the server; exit 1 if it fails. |
--timeout <SECS> | With --wait, give up after this many seconds. |
Threads already as asked are left alone. The change shows in Airpost at once and reaches the server in the background. airpost undo takes it back.
$ airpost archive --query 'from:newsletter@example.com before:30d' --dry-run
Would archive 12 threads:
DATE FROM SUBJECT ID
Oct 10 Example Weekly This week at Example 91be2c07
...
$ airpost archive --query 'from:newsletter@example.com before:30d' --wait
Archived 12 threads; task 6f2a91c0
Done: the server has the changes.
$ airpost star 3a9f01b2 77d0c3e9
Starred 1 thread (1 thread already starred); task b10e4d77
$ airpost move Receipts c24e8a10
Moved 1 thread to Receipts; task 0c9d5e12
With several accounts each account gets its own line (you@gmail.com: Archived 3 threads), then Queued tasks ....
Related: undo, search, task wait.
snooze, unsnooze
airpost snooze --until <WHEN> <THREAD_ID>...
airpost unsnooze <THREAD_ID>...
snooze moves threads to Snoozed until a time. unsnooze ends a snooze now and puts the threads back in the inbox.
$ airpost snooze --until 'tomorrow 8:00' 3a9f01b2
Snoozed 1 thread until 2026-11-17 08:00 CET
--json: {"accounts": [{"accountId", "threadIds", "taskIds", "undo"}], "until"}; until (Unix seconds) only for snooze.
remind
airpost remind <THREAD_ID|MESSAGE_ID|DRAFT_ID> --in <WHEN>
Bring a thread back to the top of the inbox if no one has replied by a time. Given a draft, the reminder goes with it when it is sent.
| Flag | Description |
|---|---|
--in <WHEN> | When. |
--clear | Remove the reminder. |
undo, redo
undo takes back airpost’s last change to threads (archive, trash, move, labels, read, star, spam, snooze), from the engine’s undo log. redo makes it again.
| Argument / flag | Applies to | Description |
|---|---|---|
TOKEN | both | The change, by the token airpost undo --list shows (or a command’s undo field in --json). |
--any | both | The latest change of any client (Airpost, an agent, a script), not only airpost’s. |
--wait | both | Wait until the change has reached the server; exit 1 if it fails. |
--timeout <SECS> | both | With --wait, give up after this many seconds. |
--list | undo | Show the log instead, newest first, with tokens. |
--mine | undo | With --list, airpost’s own changes only. |
-n, --limit <LIMIT> | undo | With --list, at most this many. |
$ airpost undo --list -n 3
WHEN CLIENT CHANGE STATE TOKEN
14:10 airpost-cli Archived 12 threads done u-81f2
14:02 airpost-mcp Moved 1 thread done u-80aa
Nov 14 airpost-desktop Marked 3 threads read undone (redo) u-7c19
$ airpost undo
Undid: Archived 12 threads (airpost-cli)
Undoing a send that has already gone prints Too late: the message was already sent and exits 1.
unsubscribe
airpost unsubscribe <MESSAGE_ID> [--method one-click|mailto|web]
Unsubscribe from the mailing list a message came from. --method restricts it to one way: one-click asks the list’s server directly (Unsubscribed (one-click).), mailto sends the unsubscribe message, and web prints the page to open (This list unsubscribes on the web; open ...).
--json: {"method", "ok", "url", "error", "taskId"}. ok is false with error when it failed (exit 1); taskId is the send task for mailto.
Folders and labels
label create, rename, delete
| Subcommand | Description |
|---|---|
label create <NAME> | Create a label on the account (--account, or the only one) and wait until the server has it. / nests it: Work/Clients. |
label rename <LABEL> <NEW_NAME> | Rename. The new name is the whole name, / between levels. |
label delete <LABEL> | Delete. Its mail stays, without the label. |
folder
For accounts other than Gmail.
| Subcommand | Description |
|---|---|
folder create <NAME> | Create a folder and wait until the server has it. / nests it: Projects/2026. |
folder rename <FOLDER> <NEW_NAME> | Rename. The new name is the whole name. |
folder delete <FOLDER> | Delete. The server deletes the mail in it too, so a folder holding threads is refused without --force. |
folder empty <trash|spam|FOLDER> | Delete every message in it for good. Asks first. trash and spam empty them in every account without --account. |
Flags for create, rename, delete (and label create, rename, delete):
| Flag | Description |
|---|---|
--no-wait | Queue the change and return without waiting for the server. |
--timeout <SECS> | Give up waiting after this many seconds. Default 60. |
--force | folder delete only: delete it even though it holds threads. |
$ airpost label create Work/Clients -a you@gmail.com
Created label Work/Clients (id 1f8e0b6a)
$ airpost folder create Projects/2026 -a you@fastmail.com --no-wait
Queued: created folder projects/2026; task 4e7b19a3 (`airpost task wait 4e7b19a3`)
--json with --no-wait: {"accountId", "taskId"}. When it waits: {"accountId", "taskId", "status"} plus label or folder with the created model on create.
Flags for folder empty:
| Flag | Description |
|---|---|
--dry-run | Show what would be deleted and delete nothing. |
-y, --yes | Don’t ask first. Needed without a terminal, and with --json. |
--wait | Wait until the server has deleted them; exit 1 if it fails. |
--timeout <SECS> | With --wait, give up after this many seconds. |
folder empty --dry-run --json: {"dryRun": true, "accounts": [{"accountId", "email", "threads", "folder": {"id", "path", "role"}}]}. Without --dry-run each account also has taskId.
Drafts and sending
A draft is saved to the account and shows in Airpost; nothing goes out until draft send. Write it (new, reply, reply-all, forward), change it (edit), check it (validate), then send it now, later (--at) or with an undo window (--undo). Drafts are named by the id from draft list (or the id these commands print) or by Message-ID.
draft new, reply, reply-all, forward
airpost draft new --to bob@example.com --subject "Lunch" --body "Thursday?"
airpost draft reply <MESSAGE_ID|THREAD_ID> --body-file reply.txt
airpost draft forward <MESSAGE_ID|THREAD_ID> --to carol@example.com
new writes from --account (default: the default sending account). reply, reply-all and forward take a message id, or a thread id for its newest message that isn’t a draft.
| Flag | Description |
|---|---|
--to <ADDRESSES> | Recipients, replacing the draft’s: addresses or Name <address>, comma-separated or repeated. |
--cc <ADDRESSES> | Cc recipients, as --to. |
--bcc <ADDRESSES> | Bcc recipients, as --to. |
--subject <SUBJECT> | The subject, replacing the draft’s. |
--body <BODY> | The text, written above the signature and quoted text. Plain text unless --html. |
--body-file <FILE|-> | Read the text from a file, or stdin with -. |
--html | The text is HTML, and a new draft an HTML one. |
--plain | A plain-text draft. Without --html or --plain the draft follows the composer’s setting (core.composing.html). |
--attach <PATH> | Attach a file; repeatable. A file the draft already has isn’t attached again. |
--template <NAME> | Write the text from a template, as the composer’s template picker does. |
--remind-in <WHEN> | Remind you if no one replies by then. |
--track-opens | Track opens. Needs an Airpost server that offers tracking, and an HTML draft. |
--track-links | Track link clicks. Same requirements. |
--prefer-existing | reply, reply-all: edit the draft already answering the message, if there is one. The default. |
--no-prefer-existing | reply, reply-all: always start a new draft. |
$ airpost draft reply 77d0c3e9 --body "Sounds good, see you then."
Saved draft e2a4c771 in thread 77d0c3e9 to Bob Smith <bob@example.com>: Re: Lunch on Thursday?
When reply revises a draft that already answers the message, the line starts Updated instead of Saved. Attached: ... and Reminder: ... lines follow when they apply.
draft edit
airpost draft edit <DRAFT_ID|MESSAGE_ID> [flags]
Change a draft in place. Takes --to, --cc, --bcc, --subject, --body, --body-file, --html, --attach, --remind-in, --track-opens and --track-links as above, plus:
| Flag | Description |
|---|---|
--detach <NAME|ID> | Remove an attachment, by file name or id; repeatable. |
Refused while the draft is being sent or scheduled to send.
draft validate
airpost draft validate <DRAFT_ID|MESSAGE_ID>
Run the checks send runs, without sending. Errors (no recipients, a bad address) exit 1; warnings (no subject, a forgotten attachment) don’t.
$ airpost draft validate e2a4c771
airpost: warning: ...
Draft e2a4c771 can be sent
draft send
airpost draft send <DRAFT_ID|MESSAGE_ID> [flags]
Send a draft now, later, or after an undo window. The validate checks run first: errors stop it, warnings are printed. Once it goes it can’t be called back.
| Flag | Description |
|---|---|
--archive | Archive the thread once it is sent. |
--wait | Wait until the mail has gone; exit 1 if the send fails. |
--timeout <SECS> | With --wait, give up after this many seconds. |
--at <WHEN> | Send later, at this time. The engine sends it then, with or without Airpost open. |
--undo <SECS> | Hold the send this many seconds (at most 3600); draft cancel-send calls it back until then. |
--remind-in <WHEN> | Remind you if no one replies by then. |
--track-opens, --track-links | As above. |
$ airpost draft send e2a4c771
Sending draft <message-id> (task 9a0f33c1; `airpost task wait 9a0f33c1` waits for it)
$ airpost draft send e2a4c771 --at 'tomorrow 9:00'
Draft e2a4c771 sends 2026-11-17 09:00 CET (`airpost draft cancel-send e2a4c771` stops it until then)
$ airpost draft send e2a4c771 --wait
SendDraftTask 9a0f33c1 complete
Related: draft scheduled, remind, tracking, undo (undoes a send still in its --undo window).
Other draft commands
| Subcommand | Description |
|---|---|
draft cancel-send <DRAFT_ID|MESSAGE_ID> | Stop a pending send (scheduled with --at or waiting out --undo). The draft stays. |
draft delete <DRAFT_ID|MESSAGE_ID> | Delete a draft. A pending send is cancelled with it; one already going out can’t be. |
draft scheduled | Drafts waiting to send, soonest first, and scheduled sends that failed. |
draft list [-n LIMIT] | Unsent drafts, newest first. -n is per account, default 50. |
draft list columns are DATE, TO, SUBJECT, FILES, THREAD, ID; draft scheduled columns are SEND AT, STATE, TO, SUBJECT, ID, where STATE is scheduled (--at), undo (waiting out --undo) or failed.
tracking
Opens and link clicks of sent mail that had tracking on.
| Command | Description |
|---|---|
tracking <MESSAGE_ID> | A sent message’s opens and clicks. |
tracking list | Sent messages with tracking on, newest first. |
tracking links | The most clicked tracked links. |
| Flag | Applies to | Description |
|---|---|---|
--type <opens|links|either> | list | Only messages tracking this. Default either. |
--since <WHEN> | list, links | Only mail sent since then: 3h, 7d, 2w, or a date. |
-n, --limit <LIMIT> | list, links | How many (default 50 messages, 10 links). |
tracking list columns are DATE, TO, SUBJECT, OPENS, CLICKS, ID.
$ airpost tracking 7c41e0a2
Proposal for Q1 (2026-11-11 17:02 +01:00)
Opens: 2
2026-11-12 09:14 +01:00 dana@example.com
2026-11-12 13:40 +01:00 dana@example.com
Clicks: 1
1 https://example.com/pricing
2026-11-12 09:15 +01:00 dana@example.com
Without tracking data, tracking <MESSAGE_ID> exits 1 with message <id> wasn't sent with tracking on.
Templates, signatures and rules
template
Alias: templates. The composer’s templates (Preferences > Templates).
| Subcommand | Description |
|---|---|
template list | Name, subject, variables and the start of the text. |
template show <NAME> | Subject, variables and text (HTML in --json). |
template save [NAME] | Save a template from text, or from a draft. Names are letters, digits, spaces, - and _; a name in use gets a number unless --replace. |
template delete <NAME> | Delete a template. |
template save flags:
| Flag | Description |
|---|---|
--subject <SUBJECT> | The subject a new draft from the template gets. |
--body <BODY> | The text, plain unless --html; {{name}} becomes a variable. |
--body-file <FILE|-> | Read the text from a file, or stdin with -. |
--html | The text is HTML. |
--from-draft <DRAFT_ID> | Save this draft as the template (the text above the signature and quote, named after the subject). |
--replace | Write over the template of that name. |
airpost template save 'Intro call' --subject 'Quick intro' \
--body 'Hi {{name}}, would you have 20 minutes next week?'
airpost template show 'Intro call' --json | jq -r '.template.variables[]'
signature
Alias: signatures. The composer’s signatures (Preferences > Signatures).
| Subcommand | Description |
|---|---|
signature list | Id, name, the addresses that start with each, and the start of the text. |
signature show <NAME|ID> | The text (HTML in --json) and the addresses that use it. |
signature set <NAME|ID> | Save a signature: the one with that name or id, else a new one. |
signature delete <NAME|ID> | Delete; the addresses that used it start without one. |
signature default <NAME|ID|none> | The signature an address starts new mail and replies with: the account’s address, or the addresses --for names. |
| Flag | Applies to | Description |
|---|---|---|
--title <TITLE> | set | Rename it. |
--body <BODY> | set | The text, plain unless --html. |
--body-file <FILE|-> | set | Read the text from a file, or stdin. |
--html | set | The text is HTML. |
--for <ADDRESS> | default | An account’s own address or an alias’s. Repeatable. |
Signatures live in the engine’s signatures setting, and the per-address choice in defaultSignatures, so the desktop and the CLI see the same ones.
airpost signature set Work --body-file ~/sig.html --html
airpost signature default Work --for you@work.example --for team@work.example
airpost signature default none --for you@home.example
rules
Alias: rule. Mail rules (Preferences > Mail Rules). The engine applies them to arriving mail, with or without Airpost open. A RULE is its id or name.
| Subcommand | Description |
|---|---|
rules list | The rules in the order they run. |
rules show <RULE> | Conditions and actions, and why the engine turned it off if it did. |
rules add | Add a rule to the account (--account, or the only one), after the others. |
rules update <RULE> | Change name, conditions, actions or match. |
rules remove <RULE> | Delete. Alias: delete. |
rules enable <RULE> | Turn on, also one the engine turned off after an error. |
rules disable <RULE> | Turn off. |
rules reprocess | Run the rules that are on over the inbox, newest first, showing progress. Interrupting stops the run. |
add and update flags:
| Flag | Description |
|---|---|
--name <NAME> | The rule’s name. |
--if <CONDITION> | FIELD COMPARATOR VALUE. Repeatable; on update they replace the rule’s conditions. |
--then <ACTION> | An action. Repeatable; on update they replace the rule’s actions. |
--match <all|any> | Every condition must match, or one is enough. |
--rule <JSON|-> | The rule (on update, the fields to change) as JSON, in the shape rules show --json prints, or - for stdin. |
--disabled | add only: save it turned off. |
Condition fields: from, to, cc, bcc, recipient, reply-to, attachment-name, subject, body. Comparators: contains, not-contains, begins-with, ends-with, equals, matches (a regular expression). Also has-attachment and starred, with true (the default) or false.
Actions: mark-read, star, trash, forward ADDRESS, move FOLDER; on Gmail also label LABEL, move LABEL (replacing the other labels), archive, important.
reprocess flags: --wait (also wait until the changes have reached the server; exit 1 if one fails) and --timeout <SECS> (give up, stopping the run).
airpost rules add --name Receipts --if 'from contains shop.example' --then 'move Receipts'
A rule is checked before it is saved: an unknown field, a bad expression or a missing folder is refused.
More examples:
airpost rules add -a you@gmail.com --name 'CI noise' --match any \
--if 'from equals notifications@github.com' --if 'subject contains [ci]' \
--then archive --then 'label CI'
airpost rules update 'CI noise' --then mark-read --then archive
airpost rules disable 'CI noise'
airpost rules reprocess -a you@gmail.com --wait
rules list columns are NAME, ACCOUNT, STATE, IF, THEN, ID. --json prints {"rules": [...]}; rules show --json prints one rule in the shape --rule accepts, so you can edit it and feed it back:
airpost rules show 'CI noise' --json > rule.json
# edit rule.json
airpost rules update 'CI noise' --rule - < rule.json
For example, airpost rules add --name Receipts --if 'from contains shop.example' --then 'move Receipts' --json prints a rule like:
{
"rule": {
"id": "local-6f1c02ab-9d4e",
"accountId": "54500b8c",
"name": "Receipts",
"conditionMode": "all",
"conditions": [{"templateKey": "from", "comparatorKey": "contains", "value": "shop.example"}],
"actions": [{"templateKey": "changeFolder", "value": "<folder id>", "valueName": "Receipts"}],
"disabled": false
}
}
Contacts and calendar
contacts
airpost contacts <QUERY>... [-n LIMIT]
Contacts whose name or address starts with the query’s words. Default limit 50.
contact
| Subcommand | Description |
|---|---|
contact get <CONTACT_ID> | A contact’s details. |
contact create | A new contact in the account’s address book. |
contact update <CONTACT_ID> | Change a contact; the fields given replace the stored ones. |
contact import <FILE> | Add the vCards of a .vcf file (or - for stdin) as new contacts. |
contact export <CONTACT_ID>... | Print contacts as a .vcf file. |
create and update flags: --patch <JSON> (fields in the shape contact get --json prints under data), --name <NAME> ("Given Family"), --email, --phone, --company, --title, --notes.
airpost contacts dana
airpost contact create --name 'Dana Ruiz' --email dana@example.com --company Acme
airpost contact import ~/Downloads/team.vcf
airpost contact export k_12 k_13 > two.vcf
contacts columns are NAME, EMAIL, REFS (how often the address appears in mail, which orders the list), plus ACCOUNT with several accounts. contact import prints Imported <n> contacts into <account>.
calendars
The calendars: id, account, name, and whether each is read-only.
calendar
| Subcommand | Description |
|---|---|
calendar sync | Start a calendar pass now. |
calendar list | Events between two times, every occurrence of a repeating one. |
calendar create | Create an event; with guests it is organised by the account. |
calendar update <EVENT_ID> | Change or delete an event, one occurrence, or it from one occurrence on. |
calendar rsvp <EVENT_ID> <accepted|tentative|declined> | Answer an invitation and tell the organizer by mail, or propose another time. |
calendar list:
| Flag | Description |
|---|---|
--from <WHEN> | From; now by default. |
--to <WHEN> | To; a week after --from by default. |
--calendar <ID> | Only these calendars. |
calendar create:
| Flag | Description |
|---|---|
--calendar <ID> | Required. The calendar’s id (airpost calendars). Give --account when there are several accounts. |
--title <TITLE> | Required. |
--start <WHEN> | Required. |
--end <WHEN> | An hour after --start by default (a day for --all-day). |
--all-day | An all-day event. |
--location <LOCATION> | |
--description <DESCRIPTION> | |
--guest <EMAIL> | Guests’ addresses. |
--repeat <RULE> | An RRULE, e.g. FREQ=WEEKLY;BYDAY=MO. |
calendar update:
| Flag | Description |
|---|---|
--scope <this|following|all> | Which occurrences of a repeating event. Default all. |
--occurrence <WHEN> | The occurrence this or following starts from, by its start. |
--start, --end <WHEN> | New times. |
--title, --location, --description | New values. |
--delete | Delete instead. |
calendar rsvp: --comment <COMMENT>, and --propose-start <WHEN> with --propose-end <WHEN> for a counter-proposal.
WHEN is a date and time such as 2026-11-02T14:30, read in your local time zone.
airpost calendars
airpost calendar list --from 2026-11-17 --to 2026-11-21
airpost calendar create --calendar c_work --title 'Design review' \
--start 2026-11-19T14:00 --guest lee@example.com
airpost calendar update e_77 --start 2026-11-19T15:00 --end 2026-11-19T16:00
airpost calendar rsvp e_77 accepted --comment 'See you there'
calendar list columns are WHEN, TITLE, EVENT; with nothing in range it prints No events. create and update print one line per write, Queued: <kind> <eventId>, or Nothing to change. rsvp prints Answered accepted as you@work.example; the organizer is told by mail, or Proposed a new time to the organizer.
AI
Through the provider set up in Preferences > AI. See AI.
| Subcommand | Description |
|---|---|
ai summarize <THREAD_ID> [--refresh] | Summarize a thread, printing the text as the model writes it. --refresh asks the model again instead of printing the cached summary. |
ai triage [THREAD_ID]... [--since AGE] | Triage inbox threads (needs-reply, important, …) and wait until done. --since is 7d, 2w, or days (default 7d). |
ai usage [--days DAYS] | Tokens used per day, provider and feature. Default 30 days. |
airpost ai summarize 3a9f01b2
airpost ai triage --since 2w
airpost ai usage --days 7 --json | jq 'map(.inputTokens + .outputTokens) | add'
ai triage prints <account>: triaged <done> of <n> threads per account, and exits 1 if a run stops early (the account stopped, the job was cancelled or triage was turned off).
Settings and tasks
settings
The settings the engine keeps for every client (undo send, the default sending account, signatures, …).
| Subcommand | Description |
|---|---|
settings get [KEY]... | The stored values, of these keys or every key. A key without a value is left out. |
settings set <KEY> <VALUE> | Store a value: JSON (15000, true, {...}), else the text as a string. null clears the key. |
settings get --json prints {"values": {"<key>": <value>}}.
task
Alias: tasks. The engine’s task queue.
| Subcommand | Description |
|---|---|
task list | Pending tasks first, oldest queued first, then finished ones, newest first. |
task queue <JSON|-> | Queue a task: its JSON, or - for stdin. id, aid and status are filled in when missing. |
task cancel <ID> | Ask the engine to cancel a task. |
task wait <ID> | Wait until a task completes; exit 1 if it fails or doesn’t exist. |
$ airpost task list -n 3
CLASS STATUS ERROR ID
SendDraftTask remote 9a0f33c1
ChangeFolderTask complete 6f2a91c0
SyncbackCategoryTask complete 4e7b19a3
$ airpost task wait 9a0f33c1
SendDraftTask 9a0f33c1 complete
task list --json is a bare array of task models. task queue prints Queued <class> <id> (<status>), and with --json the task after its local phase. task cancel --json prints {"accountId", "taskId"}. task wait --json and task queue --wait --json print the finished task.
| Flag | Applies to | Description |
|---|---|---|
--status <STATUS> | list | Only these statuses: local, remote, complete, cancelled. |
--class <CLASS> | list | Only this class, e.g. SendDraftTask. |
--header-message-id <ID> | list | Only tasks naming this draft. |
-n, --limit <LIMIT> | list | Tasks per account (default 50). |
--wait | queue | Wait until the task completes; exit 1 if it fails. |
--timeout <SECS> | queue, wait | Give up after this many seconds. |
rpc
airpost rpc <METHOD> [PARAMS]
Send one raw JSON-RPC request to the engine and print its result. PARAMS is the params object; accountId picks the engine when several run.
airpost rpc engine.status
airpost rpc threads.get '{"accountId": "54500b8c", "id": "3a9f01b2"}'
It prints the result as indented JSON, or compact with --json. Treat it as a debugging tool: methods change between versions, and a raw call can write to your account.
Services
These install and manage launchd or systemd user units. They’re covered in Background services.
| Command | Description |
|---|---|
engine install|uninstall|start|stop|restart | The engine, started at login. |
gateway install|uninstall|start|stop|restart|pair | The web client’s server, started on the first connection. |
mcp-http install|uninstall|start|stop|restart | airpost-mcp http, started on the first connection. |
service install|uninstall|list | Service plugins’ background programs. |
uninstall | Remove every unit airpost installed for the profile, and the PATH link. |
skill
airpost skill install|uninstall|print installs the agent skill for airpost into Claude Code and Codex. See Agent skill.