afmail CLI reference

Let your AI agent work your inbox — email pulled into plain files it reads, sorts, and drafts on your machine, with nothing sent until you confirm.

afmail is compiled from a closed cli-spec-v1 registry: one source for argv parsing, typed invocation values, which parameter combinations are legal, output contracts, and help. An invocation runs only when it matches exactly one registered combination.

Global arguments

AFDATA registers these itself, so the syntax in Commands leaves them out.

Argument	Where	What it does
`--help`	every command	Every legal shape of that command, complete, plus its subcommands. JSON by default; `--output plain` for a terminal.
`--version`	afmail only	Name, version, and build identity as one protocol result.
`--docs`	afmail only	This document, rendered from the registry.
`--output <FORMAT>`	per output contract	Render as json, yaml, plain (default `json`).
`--output-to <DESTINATION>`	per output contract	Route results and diagnostics to split, stdout, stderr (default `split`).
`--stdout-file <PATH>`, `--stderr-file <PATH>`	per output contract	Append that stream to a file instead.

Success output is protocol events, on those terms, unless a command’s own Output line says otherwise.

A shape is one legal set of arguments that may appear together, under a stable id. Where a command has more than one, each id is a heading below. --help returns them all at once, so discovering a command costs one call; there is no recursive mode across commands, and this document is that view.

Commands

afmail api export — Write the generated OpenAPI document and standalone JSON Schemas.
afmail api serve — Serve the typed afmail HTTP API and its OpenAPI/JSON Schema documents.
afmail case add — Add a message to this existing case.
afmail case archive — Archive this active case.
afmail case create — Create a new case and return its stable UID/ref.
afmail case delete — Delete an empty case.
afmail case draft attach — Copy or reference a file and add it to a draft’s attachments.
afmail case draft change — Change an existing editable draft in place.
afmail case draft list — List local drafts with their current status.
afmail case draft new — Scaffold a new outbound draft (not a reply) in this case.
afmail case draft remove — Remove a local draft and any queued outbound item for it.
afmail case draft reply — Scaffold a reply draft to a message, prefilled and quoting the original.
afmail case draft review — Open a review session for this draft.
afmail case draft send — Queue this draft to be sent and recorded in the case after push succeeds.
afmail case draft show — Show an existing draft as a typed render document.
afmail case draft upload — Queue this draft to be uploaded to the remote Drafts mailbox.
afmail case draft validate — Validate a draft under the case drafts directory.
afmail case list — List compact case locators.
afmail case merge — Merge another case into this case.
afmail case move — Move this case to another group.
afmail case notes append — Append text to case notes markdown.
afmail case notes replace — Replace case notes markdown with text.
afmail case notes show — Show case notes markdown.
afmail case remove — Remove one message from this case and return it to triage.
afmail case rename — Rename this case’s human-readable name without changing its UID.
afmail case review — Open a review session for this case, including editable notes.
afmail case set-summary — Set or replace one case entry summary.
afmail case show — Show the exact typed case collection document used by Markdown and Review.
afmail case suggestion clear — Clear exactly the current suggestion round.
afmail case suggestion set — Replace the current suggestion and clear any human review of the prior round.
afmail case tag — Add a case organization tag.
afmail case trash — Move every message in this case to local trash and queue Trash moves.
afmail case unarchive — Move this archived case back to an active case group.
afmail case untag — Remove a case organization tag.
afmail config add — Add an element to a keyed list such as identities.
afmail config get — Get one config key.
afmail config remove — Remove a keyed-list element by its slug.
afmail config set — Set one config key. Multiple values become an array for array keys.
afmail config show — Show effective config after applying built-in defaults.
afmail contact create — Create a new contact record.
afmail contact delete — Delete a contact.
afmail contact email add — Add an email address to the contact.
afmail contact email remove — Remove an email address from the contact.
afmail contact extract — Extract stub contacts from message senders not yet in the contact list.
afmail contact list — List contacts, optionally filtered by group, tag, org, or role.
afmail contact move — Move a contact to a different group.
afmail contact notes append — Append text to contact notes markdown.
afmail contact notes replace — Replace contact notes markdown with text.
afmail contact notes show — Show the typed contact document with raw notes Markdown.
afmail contact phone add — Add a phone number to the contact.
afmail contact phone remove — Remove a phone number from the contact.
afmail contact rename — Rename a contact’s display name.
afmail contact show — Show the exact typed contact document used by its Markdown template.
afmail contact tag — Add a tag to a contact.
afmail contact untag — Remove a tag from a contact.
afmail demo init — Create a normal workspace wired to the local demo mail server.
afmail demo serve — Run the local demo IMAP and SMTP servers until interrupted.
afmail doctor — Check afmail workspace consistency without inspecting Git.
afmail doctor repair — Repair only unambiguous afmail-generated state.
afmail init — Initialize the current directory or a child path as an afmail workspace.
afmail log case — List events for one case id.
afmail log list — List recent audit events.
afmail log message — List events for one message id.
afmail log notification — List events for one notification collection.
afmail log tail — Tail recent audit events as JSON data.
afmail message attachment fetch — Fetch one attachment by MIME part id, or all attachments when omitted.
afmail message list — List messages by sender, subject, date, or workspace scope.
afmail message show — Show the exact typed message document used by Markdown and Review templates.
afmail message spam — Mark junk/phishing/malware/suspicious mail locally, show it under spam/, and queue a Junk move.
afmail message trash — Explicitly discard this message locally, show it under trash/, and queue a Trash move.
afmail message unspam — Mark a spam false positive as triage and queue a move out of Junk when needed.
afmail message untrash — Mark a trash false positive as triage and queue a move out of Trash when needed.
afmail notification add — File an existing message into this notification collection.
afmail notification create — Create a notification collection and optionally file one message.
afmail notification delete — Delete an empty notification collection.
afmail notification list — List compact notification collections.
afmail notification move — Move a notification message to another notification collection.
afmail notification notes append — Append text to notification notes markdown.
afmail notification notes replace — Replace notification notes markdown with text.
afmail notification notes show — Show notification notes markdown.
afmail notification remove — Remove a notification message from this collection and return it to triage.
afmail notification rename — Rename this notification collection’s human-readable name without changing its UID.
afmail notification review — Open a review session for this notification and its persisted suggestion.
afmail notification set-summary — Set or replace one notification entry summary.
afmail notification show — Show the exact typed notification document used by Markdown and Review.
afmail notification suggestion clear — Clear exactly the current suggestion round.
afmail notification suggestion set — Replace the current suggestion and clear any human review of the prior round.
afmail pull — Read configured IMAP mailbox ids into local message files without changing remote mail.
afmail purge — Permanently delete old local spam, trash, and remote-deleted records together.
afmail purge deleted — Permanently delete old local records whose remote message disappeared.
afmail purge spam — Permanently delete old local spam records.
afmail purge trash — Permanently delete old local trash records.
afmail push — Push queued local work to IMAP and SMTP.
afmail push list — Preview the complete resolved push plan without writing.
afmail remote folders — List IMAP folders/mailboxes.
afmail remote test — Test configured IMAP and SMTP access without sending mail.
afmail render refresh — Rebuild generated case and notification read views.
afmail render templates — Export built-in language templates, keeping existing files unless forced.
afmail skill install — Install the Agent-First Mail skill.
afmail skill status — Show whether the Agent-First Mail skill is installed and valid.
afmail skill uninstall — Remove an afmail-managed Agent-First Mail skill.
afmail status — Report workspace health, counts, and latest pull/push progress.
afmail triage list — List compact untriaged message locators.
afmail triage review — Open a review session for persisted triage suggestions.
afmail triage suggestion clear — Clear exactly the current suggestion round.
afmail triage suggestion set — Replace the current suggestion and clear any human review of the prior round.

`afmail api export`

Write the generated OpenAPI document and standalone JSON Schemas.

afmail api export [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--directory <DIR>] [--force]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--directory`	Destination directory
`--force`	Replace existing generated files

`afmail api serve`

Serve the typed afmail HTTP API and its OpenAPI/JSON Schema documents.

afmail api serve [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--mode <local|lan>] [--port <PORT>] [--access-token-secret <SOURCE>]

Output: protocol events; --output json/yaml/plain (default json), --output-to stdout/stderr (default stdout); redirect with --stdout-file or --stderr-file.

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--mode`	Network exposure mode
`--port`	TCP port. Use 0 to let the operating system choose an available port.
`--access-token-secret`	Bearer credential; falls back to AFMAIL_API_ACCESS_TOKEN_SECRET. (the value, or where to read it: env:NAME, file[+FORMAT]:PATH#DOT_PATH, literal:VALUE)

`afmail case add`

Add a message to this existing case.

afmail case add [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <MESSAGE_ID>... [--summary <TEXT>] [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`MESSAGE_ID`	Message ids to add
`--summary`	Short summary for this message in the case
`--reason`	Why this message belongs in this case; required by default

`afmail case archive`

Archive this active case.

afmail case archive [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--reason`	Why this case is ready to archive; required by default

`afmail case create`

Create a new case and return its stable UID/ref.

afmail case create [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] --name <NAME> --group <GROUP> [--message <MESSAGE_ID>] [--summary <TEXT>] [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--name`	Human-readable case name used in case.md and the directory suffix
`--group`	Case category/group, for example support, invoice, 客服, 发票, 合同, or 退款
`--message`	First message to add to the case
`--summary`	Short summary for the first message
`--reason`	Why this case is being created

`afmail case delete`

Delete an empty case.

afmail case delete [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> [--allow-notes] [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--allow-notes`	Also delete notes.md when it contains user-authored notes
`--reason`	Why this case should be deleted; required by default

`afmail case draft attach`

Copy or reference a file and add it to a draft’s attachments.

afmail case draft attach [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> <PATH>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`DRAFT_NAME`	Draft markdown file under the case drafts directory
`PATH`	Local file path to attach

`afmail case draft change`

Change an existing editable draft in place.

`case-draft-change-recipients-body` — Keep or replace Cc and Bcc, with an optional inline body

afmail case draft change [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--subject <TEXT>] [--to <ADDRESS>...] [--identity <SLUG>] [--cc <ADDRESS>...] [--bcc <ADDRESS>...] [--body <TEXT>]

`case-draft-change-recipients-body-file` — Keep or replace Cc and Bcc, with the body read from a file

afmail case draft change [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--subject <TEXT>] [--to <ADDRESS>...] [--identity <SLUG>] [--cc <ADDRESS>...] [--bcc <ADDRESS>...] --body-file <PATH>

`case-draft-change-clear-cc-body` — Clear Cc and keep or replace Bcc, with an optional inline body

afmail case draft change [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--subject <TEXT>] [--to <ADDRESS>...] [--identity <SLUG>] --clear-cc [--bcc <ADDRESS>...] [--body <TEXT>]

`case-draft-change-clear-cc-body-file` — Clear Cc and keep or replace Bcc, with the body read from a file

afmail case draft change [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--subject <TEXT>] [--to <ADDRESS>...] [--identity <SLUG>] --clear-cc [--bcc <ADDRESS>...] --body-file <PATH>

`case-draft-change-clear-bcc-body` — Clear Bcc and keep or replace Cc, with an optional inline body

afmail case draft change [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--subject <TEXT>] [--to <ADDRESS>...] [--identity <SLUG>] [--cc <ADDRESS>...] --clear-bcc [--body <TEXT>]

`case-draft-change-clear-bcc-body-file` — Clear Bcc and keep or replace Cc, with the body read from a file

afmail case draft change [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--subject <TEXT>] [--to <ADDRESS>...] [--identity <SLUG>] [--cc <ADDRESS>...] --clear-bcc --body-file <PATH>

`case-draft-change-clear-cc-bcc-body` — Clear Cc and Bcc, with an optional inline body

afmail case draft change [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--subject <TEXT>] [--to <ADDRESS>...] [--identity <SLUG>] --clear-cc --clear-bcc [--body <TEXT>]

`case-draft-change-clear-cc-bcc-body-file` — Clear Cc and Bcc, with the body read from a file

afmail case draft change [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--subject <TEXT>] [--to <ADDRESS>...] [--identity <SLUG>] --clear-cc --clear-bcc --body-file <PATH>

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`DRAFT_NAME`	Draft markdown file under the case drafts directory
`--subject`	Replacement subject
`--to`	Replacement To list; when provided it replaces all To recipients
`--identity`	Workspace identity slug to send as. Defaults to the configured default identity.
`--cc`	Replacement Cc list; when provided it replaces all Cc recipients
`--clear-cc`	Clear all Cc recipients
`--bcc`	Replacement Bcc list; when provided it replaces all Bcc recipients
`--clear-bcc`	Clear all Bcc recipients
`--body`	Replacement draft body text
`--body-file`	Path to a file whose contents replace the draft body

`afmail case draft list`

List local drafts with their current status.

afmail case draft list [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix

`afmail case draft new`

Scaffold a new outbound draft (not a reply) in this case.

`case-draft-new-to-inline-body` — Visible recipient with an inline body or the default template

afmail case draft new [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --to <ADDRESS>... --subject <TEXT> [--cc <ADDRESS>...] [--bcc <ADDRESS>...] [--identity <SLUG>] [--body <TEXT>]

`case-draft-new-to-body-file` — Visible recipient with the body read from a file

afmail case draft new [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --to <ADDRESS>... --subject <TEXT> [--cc <ADDRESS>...] [--bcc <ADDRESS>...] [--identity <SLUG>] --body-file <PATH>

`case-draft-new-bcc-only-inline-body` — Only blind recipients, with an inline body or the default template

afmail case draft new [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --subject <TEXT> [--cc <ADDRESS>...] --bcc <ADDRESS>... [--identity <SLUG>] [--body <TEXT>]

`case-draft-new-bcc-only-body-file` — Only blind recipients, with the body read from a file

afmail case draft new [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --subject <TEXT> [--cc <ADDRESS>...] --bcc <ADDRESS>... [--identity <SLUG>] --body-file <PATH>

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--to`	Recipient address; repeat for more than one
`--subject`	Draft subject
`--cc`	Cc address; repeat for more than one
`--bcc`	Bcc address; repeat for more than one
`--identity`	Workspace identity slug to send as. Defaults to the configured default identity.
`--body`	Draft body text
`--body-file`	Path to a file whose contents become the draft body

`afmail case draft remove`

Remove a local draft and any queued outbound item for it.

afmail case draft remove [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`DRAFT_NAME`	Draft markdown file under the case drafts directory
`--reason`	Why this draft should be removed; required by default

`afmail case draft reply`

Scaffold a reply draft to a message, prefilled and quoting the original.

`case-draft-reply-inline-body` — Body given inline, or left to the default reply template

afmail case draft reply [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <MESSAGE_ID> [--identity <SLUG>] [--all] [--bcc <ADDRESS>...] [--body <TEXT>]

`case-draft-reply-body-file` — Body read from a file; the inline –body is absent here

afmail case draft reply [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <MESSAGE_ID> [--identity <SLUG>] [--all] [--bcc <ADDRESS>...] --body-file <PATH>

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`MESSAGE_ID`	Message id in this case to reply to
`--identity`	Workspace identity slug to send as. Defaults to the configured default identity.
`--all`	Reply to all original recipients (To and Cc), not just the sender
`--bcc`	Bcc address; repeat for more than one
`--body`	Draft body text. Replaces the default reply template when provided.
`--body-file`	Path to a file whose contents become the draft body

`afmail case draft review`

Open a review session for this draft.

afmail case draft review [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF> <DRAFT_NAME> [--mode <window|link|session>]

Output: protocol events; --output json/yaml/plain (default json), --output-to stdout/stderr (default stdout); redirect with --stdout-file or --stderr-file.

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`DRAFT_NAME`	Draft markdown file under the case drafts directory
`--mode`	How this reaches the person: window a browser window is open on this machine; link the page is reachable from this machine’s network at the link URL; session the session is registered only; open it with `afui session open` or reach it through `afui session serve`. Falls back to AFUI_DELIVERY, then window

`afmail case draft send`

Queue this draft to be sent and recorded in the case after push succeeds.

afmail case draft send [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`DRAFT_NAME`	Draft markdown file under the case drafts directory

`afmail case draft show`

Show an existing draft as a typed render document.

afmail case draft show [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF> <DRAFT_NAME>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`DRAFT_NAME`	Draft markdown file under the case drafts directory

`afmail case draft upload`

Queue this draft to be uploaded to the remote Drafts mailbox.

afmail case draft upload [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`DRAFT_NAME`	Draft markdown file under the case drafts directory

`afmail case draft validate`

Validate a draft under the case drafts directory.

afmail case draft validate [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <DRAFT_NAME>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`DRAFT_NAME`	Draft markdown file under the case drafts directory

`afmail case list`

List compact case locators.

`case-list-active` — List active cases; this is the default

afmail case list [--workspace <PATH>] [--log <startup|request|progress|retry>...]

`case-list-archived` — List archived cases only

afmail case list [--workspace <PATH>] [--log <startup|request|progress|retry>...] --archived

`case-list-all` — List active and archived cases together

afmail case list [--workspace <PATH>] [--log <startup|request|progress|retry>...] --all

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--archived`	List archived cases instead of active cases
`--all`	List active and archived cases together

`afmail case merge`

Merge another case into this case.

afmail case merge [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF> <OTHER_CASE_REF> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`OTHER_CASE_REF`	Case ref to merge into the primary case
`--reason`	Why these cases should be merged; required by default

`afmail case move`

Move this case to another group.

afmail case move [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --group <GROUP> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--group`	Destination group
`--reason`	Why this group better represents the case; required by default

`afmail case notes append`

Append text to case notes markdown.

afmail case notes append [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF> [--request-id <ID>] --text <TEXT>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--text`	Markdown text to append

`afmail case notes replace`

Replace case notes markdown with text.

afmail case notes replace [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF> [--request-id <ID>] --text <TEXT>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--text`	Markdown text to write

`afmail case notes show`

Show case notes markdown.

afmail case notes show [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix

`afmail case remove`

Remove one message from this case and return it to triage.

afmail case remove [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <MESSAGE_ID> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`MESSAGE_ID`	Message id to remove
`--reason`	Why this message does not belong in this case; required by default

`afmail case rename`

Rename this case’s human-readable name without changing its UID.

afmail case rename [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --name <NAME> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--name`	New human-readable case name
`--reason`	Why this name better represents the case; required by default

`afmail case review`

Open a review session for this case, including editable notes.

afmail case review [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF> [--mode <window|link|session>]

Output: protocol events; --output json/yaml/plain (default json), --output-to stdout/stderr (default stdout); redirect with --stdout-file or --stderr-file.

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--mode`	How this reaches the person: window a browser window is open on this machine; link the page is reachable from this machine’s network at the link URL; session the session is registered only; open it with `afui session open` or reach it through `afui session serve`. Falls back to AFUI_DELIVERY, then window

`afmail case set-summary`

Set or replace one case entry summary.

afmail case set-summary [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <MESSAGE_ID> --summary <TEXT> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`MESSAGE_ID`	Message id whose summary should be changed
`--summary`	New summary text
`--reason`	Why this summary is useful; required by default

`afmail case show`

Show the exact typed case collection document used by Markdown and Review.

afmail case show [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_REF>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix

`afmail case suggestion clear`

Clear exactly the current suggestion round.

afmail case suggestion clear [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --agent-suggestion-uid <UID>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--agent-suggestion-uid`	UID returned by the current suggestion set command

`afmail case suggestion set`

Replace the current suggestion and clear any human review of the prior round.

`case-suggestion-set-archive` — Suggest archiving this case

afmail case suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --case-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action archive

`case-suggestion-set-unarchive` — Suggest unarchiving this case into a group

afmail case suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --case-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action unarchive --group <GROUP>

`case-suggestion-set-move` — Suggest moving this case to another group

afmail case suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --case-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action move --group <GROUP>

`case-suggestion-set-rename` — Suggest renaming this case

afmail case suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --case-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action rename --name <NAME>

`case-suggestion-set-tag` — Suggest adding a tag

afmail case suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --case-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action tag --tag <TAG>

`case-suggestion-set-untag` — Suggest removing a tag

afmail case suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --case-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action untag --tag <TAG>

`case-suggestion-set-trash` — Suggest trashing every message in this case

afmail case suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --case-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action trash

`case-suggestion-set-delete` — Suggest deleting this case

afmail case suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --case-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action delete [--allow-notes]

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--case-review-base-hash`	Current hash returned by `afmail case show`
`--reason`	Why this complete action is being suggested
`--confidence-percent`	Optional confidence from 0 through 100
`--action`	The complete action being suggested; it decides which other arguments apply
`--group`	Destination case group
`--name`	New human-readable case name
`--tag`	Case organization tag
`--allow-notes`	Also delete notes.md when it contains user-authored notes

`afmail case tag`

Add a case organization tag.

afmail case tag [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <TAG> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`TAG`	Case organization tag
`--reason`	Why this tag is useful; required by default

`afmail case trash`

Move every message in this case to local trash and queue Trash moves.

afmail case trash [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--reason`	Why this whole case should be discarded; required by default

`afmail case unarchive`

Move this archived case back to an active case group.

afmail case unarchive [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> --group <GROUP> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`--group`	Active case group to unarchive into
`--reason`	Why this case needs active attention again; required by default

`afmail case untag`

Remove a case organization tag.

afmail case untag [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CASE_REF> <TAG> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CASE_REF`	Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
`TAG`	Case organization tag
`--reason`	Why this tag should be removed; required by default

`afmail config add`

Add an element to a keyed list such as identities.

afmail config add [--workspace <PATH>] [--log <startup|request|progress|retry>...] <KEY> <SLUG> [<KEY=VALUE>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`KEY`	Configuration key
`SLUG`	Stable slug identifying the element
`KEY=VALUE`	Element field assignment

`afmail config get`

Get one config key.

afmail config get [--workspace <PATH>] [--log <startup|request|progress|retry>...] <KEY>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`KEY`	Configuration key

`afmail config remove`

Remove a keyed-list element by its slug.

afmail config remove [--workspace <PATH>] [--log <startup|request|progress|retry>...] <KEY> <SLUG>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`KEY`	Configuration key
`SLUG`	Slug of the element to remove

`afmail config set`

Set one config key. Multiple values become an array for array keys.

afmail config set [--workspace <PATH>] [--log <startup|request|progress|retry>...] <KEY> [<VALUE>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`KEY`	Configuration key
`VALUE`	Replacement value; repeat for an array key

`afmail config show`

Show effective config after applying built-in defaults.

afmail config show [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail contact create`

Create a new contact record.

afmail contact create [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] --name <NAME> [--group <GROUP>] [--email <ADDRESS>...] [--phone <NUMBER>...] [--org <NAME>] [--role <ROLE>] [--tag <TAG>...] [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--name`	Display name for the contact
`--group`	Group. Defaults to the configured default contact group.
`--email`	Email address; repeat for more than one
`--phone`	Phone number; repeat for more than one
`--org`	Organization name
`--role`	Role or title
`--tag`	Tag; repeat for more than one
`--reason`	Why this contact is being created; required by default

`afmail contact delete`

Delete a contact.

afmail contact delete [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> [--allow-notes] [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`--allow-notes`	Also delete the contact body when it contains user-authored notes
`--reason`	Why this contact should be deleted; required by default

`afmail contact email add`

Add an email address to the contact.

afmail contact email add [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> <EMAIL> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`EMAIL`	Email address to add
`--reason`	Why this email should be associated with the contact; required by default

`afmail contact email remove`

Remove an email address from the contact.

afmail contact email remove [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> <EMAIL> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`EMAIL`	Email address to remove
`--reason`	Why this email should be removed; required by default

`afmail contact extract`

Extract stub contacts from message senders not yet in the contact list.

`contact-extract-triage` — Extract from triage messages; this is the default source

afmail contact extract [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--group <GROUP>] [--from-triage]

`contact-extract-case` — Extract from one case’s messages

afmail contact extract [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--group <GROUP>] --from-case <CASE_REF>

`contact-extract-all` — Extract from every triage and case message

afmail contact extract [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--group <GROUP>] --all

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--group`	Destination group for created contacts. Defaults to contact.default_group.
`--from-triage`	Extract from triage messages only
`--from-case`	Extract from a specific case’s messages
`--all`	Extract from all triage and case messages

`afmail contact list`

List contacts, optionally filtered by group, tag, org, or role.

afmail contact list [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--group <GROUP>] [--tag <TAG>] [--org <NAME>] [--role <ROLE>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--group`	Filter to a specific group
`--tag`	Filter by tag
`--org`	Filter by organization
`--role`	Filter by role

`afmail contact move`

Move a contact to a different group.

afmail contact move [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> --group <GROUP> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`--group`	Destination group
`--reason`	Why this contact should move groups; required by default

`afmail contact notes append`

Append text to contact notes markdown.

afmail contact notes append [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CONTACT_REF> [--request-id <ID>] --text <TEXT>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--text`	Markdown text to append

`afmail contact notes replace`

Replace contact notes markdown with text.

afmail contact notes replace [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CONTACT_REF> [--request-id <ID>] --text <TEXT>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--text`	Markdown text to write

`afmail contact notes show`

Show the typed contact document with raw notes Markdown.

afmail contact notes show [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CONTACT_REF>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix

`afmail contact phone add`

Add a phone number to the contact.

afmail contact phone add [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> <PHONE> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`PHONE`	Phone number to add
`--reason`	Why this phone number should be associated with the contact; required by default

`afmail contact phone remove`

Remove a phone number from the contact.

afmail contact phone remove [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> <PHONE> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`PHONE`	Phone number to remove
`--reason`	Why this phone number should be removed; required by default

`afmail contact rename`

Rename a contact’s display name.

afmail contact rename [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> --name <NAME> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`--name`	New display name
`--reason`	Why this name better represents the contact; required by default

`afmail contact show`

Show the exact typed contact document used by its Markdown template.

afmail contact show [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CONTACT_REF>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix

`afmail contact tag`

Add a tag to a contact.

afmail contact tag [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> <TAG> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`TAG`	Tag to add
`--reason`	Why this tag is useful; required by default

`afmail contact untag`

Remove a tag from a contact.

afmail contact untag [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <CONTACT_REF> <TAG> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`CONTACT_REF`	Contact ref: pYYYYMMDDNNN or pYYYYMMDDNNN-any-suffix
`TAG`	Tag to remove
`--reason`	Why this tag should be removed; required by default

`afmail demo init`

Create a normal workspace wired to the local demo mail server.

afmail demo init [--log <startup|request|progress|retry>...] [<PATH>] [--scenario <founder-inbox>] [--imap-port <PORT>] [--smtp-port <PORT>]

Argument	Meaning
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`PATH`	Workspace path under the current directory
`--scenario`	Built-in mailbox scenario
`--imap-port`	Local IMAP port
`--smtp-port`	Local SMTP port

`afmail demo serve`

Run the local demo IMAP and SMTP servers until interrupted.

afmail demo serve [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--verbose]

Output: protocol events; --output json/yaml/plain (default json), --output-to stdout/stderr (default stdout); redirect with --stdout-file or --stderr-file.

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--verbose`	Also report every raw IMAP and SMTP protocol line the demo server sees

`afmail doctor`

Check afmail workspace consistency without inspecting Git.

afmail doctor [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail doctor repair`

Repair only unambiguous afmail-generated state.

afmail doctor repair [--workspace <PATH>] [--log <startup|request|progress|retry>...] --confirm

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--confirm`	Apply the repair actions. Repair never runs without it, so it is part of the only registered shape.

`afmail init`

Initialize the current directory or a child path as an afmail workspace.

afmail init [--log <startup|request|progress|retry>...] [<PATH>]

Argument	Meaning
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`PATH`	Workspace path to initialize under the current directory

`afmail log case`

List events for one case id.

afmail log case [--workspace <PATH>] [--log <startup|request|progress|retry>...] <CASE_UID>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`CASE_UID`	Case UID

`afmail log list`

List recent audit events.

afmail log list [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--limit <COUNT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--limit`	Maximum number of events to return

`afmail log message`

List events for one message id.

afmail log message [--workspace <PATH>] [--log <startup|request|progress|retry>...] <MESSAGE_ID>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`MESSAGE_ID`	Message id

`afmail log notification`

List events for one notification collection.

afmail log notification [--workspace <PATH>] [--log <startup|request|progress|retry>...] <NOTIFICATION_UID>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`NOTIFICATION_UID`	Notification UID

`afmail log tail`

Tail recent audit events as JSON data.

afmail log tail [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail message attachment fetch`

Fetch one attachment by MIME part id, or all attachments when omitted.

afmail message attachment fetch [--workspace <PATH>] [--log <startup|request|progress|retry>...] <MESSAGE_ID> [<PART_ID>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`MESSAGE_ID`	Message id, for example message_inbox_607146690_22
`PART_ID`	MIME part id; with none, every attachment is fetched

`afmail message list`

List messages by sender, subject, date, or workspace scope.

afmail message list [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--sender <TEXT>] [--subject-contains <TEXT>] [--since <DATE>] [--in <triage|case|notification|all>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--sender`	Only include messages whose sender or from line contains this text
`--subject-contains`	Only include messages whose subject contains this text
`--since`	Only include messages on or after this date or RFC3339 timestamp
`--in`	Limit results to one workspace scope

`afmail message show`

Show the exact typed message document used by Markdown and Review templates.

afmail message show [--workspace <PATH>] [--log <startup|request|progress|retry>...] <MESSAGE_ID>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`MESSAGE_ID`	Message id, for example message_inbox_607146690_22

`afmail message spam`

Mark junk/phishing/malware/suspicious mail locally, show it under spam/, and queue a Junk move.

afmail message spam [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID>... [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`MESSAGE_ID`	Message ids, for example message_inbox_607146690_22
`--reason`	Why this disposition is correct; required by default

`afmail message trash`

Explicitly discard this message locally, show it under trash/, and queue a Trash move.

afmail message trash [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID>... [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`MESSAGE_ID`	Message ids, for example message_inbox_607146690_22
`--reason`	Why this disposition is correct; required by default

`afmail message unspam`

Mark a spam false positive as triage and queue a move out of Junk when needed.

afmail message unspam [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID>... [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`MESSAGE_ID`	Message ids, for example message_inbox_607146690_22
`--reason`	Why this message is not spam; required by default

`afmail message untrash`

Mark a trash false positive as triage and queue a move out of Trash when needed.

afmail message untrash [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID>... [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`MESSAGE_ID`	Message ids, for example message_inbox_607146690_22
`--reason`	Why this message should not be trashed; required by default

`afmail notification add`

File an existing message into this notification collection.

afmail notification add [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> <MESSAGE_ID>... --summary <TEXT> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`MESSAGE_ID`	Message ids to file
`--summary`	Human/agent-authored summary for this notification entry
`--reason`	Why this message belongs in this notification; required by default

`afmail notification create`

Create a notification collection and optionally file one message.

`notification-create-empty` — Create an empty collection; with no message there is nothing to summarize

afmail notification create [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] --name <NAME> [--reason <TEXT>]

`notification-create-with-message` — Create the collection and file one message, which always needs a summary

afmail notification create [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] --name <NAME> [--reason <TEXT>] --message <MESSAGE_ID> --summary <TEXT>

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--name`	Human-readable notification name used in metadata and the directory suffix
`--reason`	Why this notification collection is being created
`--message`	Message to immediately file into the new collection
`--summary`	Summary for the filed message’s notification entry

`afmail notification delete`

Delete an empty notification collection.

afmail notification delete [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> [--allow-notes] [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`--allow-notes`	Also delete notes.md when it contains user-authored notes
`--reason`	Why this notification collection should be deleted; required by default

`afmail notification list`

List compact notification collections.

afmail notification list [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail notification move`

Move a notification message to another notification collection.

afmail notification move [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> <MESSAGE_ID> <NEW_NOTIFICATION_REF> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`MESSAGE_ID`	Message id to move
`NEW_NOTIFICATION_REF`	Destination notification collection ref
`--reason`	Why this collection is better; required by default

`afmail notification notes append`

Append text to notification notes markdown.

afmail notification notes append [--workspace <PATH>] [--log <startup|request|progress|retry>...] <NOTIFICATION_REF> [--request-id <ID>] --text <TEXT>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--text`	Markdown text to append

`afmail notification notes replace`

Replace notification notes markdown with text.

afmail notification notes replace [--workspace <PATH>] [--log <startup|request|progress|retry>...] <NOTIFICATION_REF> [--request-id <ID>] --text <TEXT>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`--text`	Markdown text to write

`afmail notification notes show`

Show notification notes markdown.

afmail notification notes show [--workspace <PATH>] [--log <startup|request|progress|retry>...] <NOTIFICATION_REF>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix

`afmail notification remove`

Remove a notification message from this collection and return it to triage.

afmail notification remove [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> <MESSAGE_ID> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`MESSAGE_ID`	Message id to remove
`--reason`	Why this message does not belong in this notification; required by default

`afmail notification rename`

Rename this notification collection’s human-readable name without changing its UID.

afmail notification rename [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> --name <NAME> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`--name`	New human-readable notification name
`--reason`	Why this name better represents the collection; required by default

`afmail notification review`

Open a review session for this notification and its persisted suggestion.

afmail notification review [--workspace <PATH>] [--log <startup|request|progress|retry>...] <NOTIFICATION_REF> [--mode <window|link|session>]

Output: protocol events; --output json/yaml/plain (default json), --output-to stdout/stderr (default stdout); redirect with --stdout-file or --stderr-file.

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`--mode`	How this reaches the person: window a browser window is open on this machine; link the page is reachable from this machine’s network at the link URL; session the session is registered only; open it with `afui session open` or reach it through `afui session serve`. Falls back to AFUI_DELIVERY, then window

`afmail notification set-summary`

Set or replace one notification entry summary.

afmail notification set-summary [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> <MESSAGE_ID> --summary <TEXT> [--reason <TEXT>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`MESSAGE_ID`	Message id whose summary should be changed
`--summary`	New summary text
`--reason`	Why this summary is useful; required by default

`afmail notification show`

Show the exact typed notification document used by Markdown and Review.

afmail notification show [--workspace <PATH>] [--log <startup|request|progress|retry>...] <NOTIFICATION_REF>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix

`afmail notification suggestion clear`

Clear exactly the current suggestion round.

afmail notification suggestion clear [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> --agent-suggestion-uid <UID>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`--agent-suggestion-uid`	UID returned by the current suggestion set command

`afmail notification suggestion set`

Replace the current suggestion and clear any human review of the prior round.

`notification-suggestion-set-rename` — Suggest renaming this collection

afmail notification suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> --notification-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action rename --name <NAME>

`notification-suggestion-set-delete` — Suggest deleting this collection

afmail notification suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <NOTIFICATION_REF> --notification-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action delete [--allow-notes]

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`NOTIFICATION_REF`	Notification ref: nYYYYMMDDNNN or nYYYYMMDDNNN-any-suffix
`--notification-review-base-hash`	Current hash returned by `afmail notification show`
`--reason`	Why this complete action is being suggested
`--confidence-percent`	Optional confidence from 0 through 100
`--action`	The complete action being suggested; it decides which other arguments apply
`--name`	New human-readable notification name
`--allow-notes`	Also delete notes.md when it contains user-authored notes

`afmail pull`

Read configured IMAP mailbox ids into local message files without changing remote mail.

`pull-window` — Pull a bounded window: the default initial window, or –since-days

afmail pull [--workspace <PATH>] [--log <startup|request|progress|retry>...] [<MAILBOX_ID>...] [--dry-run] [--max-new-messages <COUNT>] [--max-total-bytes <BYTES>] [--since-days <DAYS>]

`pull-all-history` — Pull every remote message; no window applies, so –since-days is absent here

afmail pull [--workspace <PATH>] [--log <startup|request|progress|retry>...] [<MAILBOX_ID>...] [--dry-run] [--max-new-messages <COUNT>] [--max-total-bytes <BYTES>] --all-history

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`MAILBOX_ID`	Configured mailbox ids to pull. With none, pulls actions.pull.default_mailbox_ids.
`--dry-run`	Estimate remote candidates and budgets without downloading or writing locally
`--max-new-messages`	Maximum number of new messages stored across all selected mailboxes
`--max-total-bytes`	Maximum new raw message bytes stored across all selected mailboxes
`--since-days`	Limit the remote candidate range to messages from the last DAYS days
`--all-history`	Include all remote history instead of the default initial window

`afmail purge`

Permanently delete old local spam, trash, and remote-deleted records together.

afmail purge [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--older-than-days <DAYS>] [--confirm <PLAN_ID>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--older-than-days`	Only purge messages in a discard state at least this many days ago. Defaults to 30.
`--confirm`	Permanently delete exactly the reviewed purge plan

`afmail purge deleted`

Permanently delete old local records whose remote message disappeared.

afmail purge deleted [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--older-than-days <DAYS>] [--confirm <PLAN_ID>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--older-than-days`	Only purge messages marked remote-deleted at least this many days ago. Defaults to 30.
`--confirm`	Permanently delete exactly the reviewed purge plan

`afmail purge spam`

Permanently delete old local spam records.

afmail purge spam [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--older-than-days <DAYS>] [--confirm <PLAN_ID>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--older-than-days`	Only purge messages marked spam at least this many days ago. Defaults to 30.
`--confirm`	Permanently delete exactly the reviewed purge plan

`afmail purge trash`

Permanently delete old local trash records.

afmail purge trash [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--older-than-days <DAYS>] [--confirm <PLAN_ID>]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--older-than-days`	Only purge messages marked trash at least this many days ago. Defaults to 30.
`--confirm`	Permanently delete exactly the reviewed purge plan

`afmail push`

Push queued local work to IMAP and SMTP.

`push-preview` — Preview the plan; nothing is written, so no plan id is confirmed

afmail push [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--dry-run]

`push-apply` — Apply one reviewed plan; this shape writes, so –dry-run is absent

afmail push [--workspace <PATH>] [--log <startup|request|progress|retry>...] --confirm <PLAN_ID>

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--dry-run`	Show planned push actions without IMAP/SMTP writes
`--confirm`	Apply exactly the reviewed plan returned by the push preview

`afmail push list`

Preview the complete resolved push plan without writing.

afmail push list [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail remote folders`

List IMAP folders/mailboxes.

afmail remote folders [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail remote test`

Test configured IMAP and SMTP access without sending mail.

afmail remote test [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail render refresh`

Rebuild generated case and notification read views.

afmail render refresh [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail render templates`

Export built-in language templates, keeping existing files unless forced.

afmail render templates [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--force]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--force`	Overwrite existing workspace templates with built-in defaults

`afmail skill install`

Install the Agent-First Mail skill.

`skill-install-every-agent` — Target every agent that supports the scope

afmail skill install [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--agent all] [--scope <personal|workspace>] [--force]

`skill-install-one-agent` — Target one named agent; only this shape accepts –skills-dir

afmail skill install [--workspace <PATH>] [--log <startup|request|progress|retry>...] --agent <codex|claude-code|opencode|hermes> [--scope <personal|workspace>] [--skills-dir <DIR>] [--force]

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--agent`	Agent to manage
`--scope`	Skill scope
`--skills-dir`	Directory that contains skill folders
`--force`	Overwrite or remove an unmanaged Agent-First Mail skill at the target path

`afmail skill status`

Show whether the Agent-First Mail skill is installed and valid.

`skill-status-every-agent` — Target every agent that supports the scope

afmail skill status [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--agent all] [--scope <personal|workspace>]

`skill-status-one-agent` — Target one named agent; only this shape accepts –skills-dir

afmail skill status [--workspace <PATH>] [--log <startup|request|progress|retry>...] --agent <codex|claude-code|opencode|hermes> [--scope <personal|workspace>] [--skills-dir <DIR>]

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--agent`	Agent to manage
`--scope`	Skill scope
`--skills-dir`	Directory that contains skill folders

`afmail skill uninstall`

Remove an afmail-managed Agent-First Mail skill.

`skill-uninstall-every-agent` — Target every agent that supports the scope

afmail skill uninstall [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--agent all] [--scope <personal|workspace>] [--force]

`skill-uninstall-one-agent` — Target one named agent; only this shape accepts –skills-dir

afmail skill uninstall [--workspace <PATH>] [--log <startup|request|progress|retry>...] --agent <codex|claude-code|opencode|hermes> [--scope <personal|workspace>] [--skills-dir <DIR>] [--force]

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--agent`	Agent to manage
`--scope`	Skill scope
`--skills-dir`	Directory that contains skill folders
`--force`	Overwrite or remove an unmanaged Agent-First Mail skill at the target path

`afmail status`

Report workspace health, counts, and latest pull/push progress.

afmail status [--workspace <PATH>] [--log <startup|request|progress|retry>...]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.

`afmail triage list`

List compact untriaged message locators.

afmail triage list [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--limit <COUNT>] [--details]

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--limit`	Maximum number of newest triage messages to return
`--details`	Include message metadata, related message ids, and case refs

`afmail triage review`

Open a review session for persisted triage suggestions.

afmail triage review [--workspace <PATH>] [--log <startup|request|progress|retry>...] [<MESSAGE_ID>...] [--mode <window|link|session>]

Output: protocol events; --output json/yaml/plain (default json), --output-to stdout/stderr (default stdout); redirect with --stdout-file or --stderr-file.

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`MESSAGE_ID`	Message ids to review. With none, reviews the current triage queue, newest first, up to a bound; the result says if any were left out.
`--mode`	How this reaches the person: window a browser window is open on this machine; link the page is reachable from this machine’s network at the link URL; session the session is registered only; open it with `afui session open` or reach it through `afui session serve`. Falls back to AFUI_DELIVERY, then window

`afmail triage suggestion clear`

Clear exactly the current suggestion round.

afmail triage suggestion clear [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID> --agent-suggestion-uid <UID>

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`MESSAGE_ID`	Message id whose current suggestion round should be cleared
`--agent-suggestion-uid`	UID returned by the current suggestion set command

`afmail triage suggestion set`

Replace the current suggestion and clear any human review of the prior round.

`triage-suggestion-set-case-create` — Suggest creating a new case from this message

afmail triage suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID> --message-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action case-create --name <NAME> --group <GROUP>

`triage-suggestion-set-case-add` — Suggest adding this message to an existing case

afmail triage suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID> --message-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action case-add --case-ref <CASE_REF>

`triage-suggestion-set-notification-create` — Suggest creating a new notification collection from this message

afmail triage suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID> --message-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action notification-create --name <NAME> --summary <TEXT>

`triage-suggestion-set-notification-add` — Suggest filing this message into an existing notification collection

afmail triage suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID> --message-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action notification-add --notification-ref <NOTIFICATION_REF> --summary <TEXT>

`triage-suggestion-set-spam` — Suggest marking this message as spam

afmail triage suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID> --message-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action spam

`triage-suggestion-set-trash` — Suggest trashing this message

afmail triage suggestion set [--workspace <PATH>] [--log <startup|request|progress|retry>...] [--request-id <ID>] <MESSAGE_ID> --message-review-base-hash <HASH> --reason <TEXT> [--confidence-percent <PERCENT>] --action trash

Arguments across every shape above:

Argument	Meaning
`--workspace`	Existing afmail workspace to operate on instead of discovering one from the current directory
`--log`	Diagnostic category to emit. Repeat the flag for more than one.
`--request-id`	Idempotency key; replaying it returns the first result instead of repeating the mutation
`MESSAGE_ID`	Message id currently in triage
`--message-review-base-hash`	Current hash returned by `afmail message show`
`--reason`	Why this complete action is being suggested
`--confidence-percent`	Optional confidence from 0 through 100
`--action`	The complete action being suggested; it decides which other arguments apply
`--name`	Name for the suggested new case or notification
`--group`	Group for the suggested new case
`--case-ref`	Existing case to add the message to
`--notification-ref`	Existing notification collection to file the message into
`--summary`	Summary for the notification entry

Exit codes

Code	Meaning
0	The command ran and succeeded.
1	The command ran and failed. The event carries a domain `error.code`.
2	The invocation was rejected before anything ran. `error.code` is one of the `cli_*` codes below.
3	Some items in a batch succeeded and some failed. The remote effects that landed stay landed, so re-running the same call is not safe; read `failures` and re-queue from there.
4	The command ran, but its output could not be written to the requested destination.

The split is the useful one for a caller: exit 2 means the call was never made, so retrying it unchanged cannot help, while exit 1 means it was.

CLI errors

Every structural failure emits one strict JSON kind:"error" event on stderr, leaves stdout empty, and exits 2. The code names the failure — cli_unknown_argument for an unknown spelling, cli_unregistered_combination for registered arguments in a mixture that is not, and one each for cli_unknown_command, cli_missing_argument_value, cli_invalid_argument_value, cli_duplicate_argument, cli_unexpected_positional, and cli_invalid_utf8. message identifies a safe argument spelling or the failure category and hint gives the command to run next; neither ever quotes a raw value, including secrets. These are decided before any config, secret source, filesystem, network, or domain I/O.

Two exit-1 codes describe the tool itself rather than the call: cli_invocation_invalid means the program misread its own resolved invocation — an unknown action id, or an argument id the selected combination cannot produce — and output_setup_failed means an output sink (--stdout-file, --stderr-file, stream redirection) could not be established. Both are defects to report, not inputs to correct; retrying the same command cannot help.

Domain failures (exit 1) carry their own stable error.code instead, drawn from whatever this tool defines rather than from the cli_* set. Error events are routinely logged, so a message never quotes a value that came from an argument able to carry a credential — a header, a cookie, a token, a password, a proxy URL, an environment value, a form field. Such an error names the argument and the shape that was wrong, and stops there. A value that cannot be a secret — a path, a dot-path, a session name — is quoted, because an error that cannot say which one it means is not worth logging either.

afmail CLI reference

Global arguments

Commands

afmail api export

afmail api serve

afmail case add

afmail case archive

afmail case create

afmail case delete

afmail case draft attach

afmail case draft change

case-draft-change-recipients-body — Keep or replace Cc and Bcc, with an optional inline body

case-draft-change-recipients-body-file — Keep or replace Cc and Bcc, with the body read from a file

case-draft-change-clear-cc-body — Clear Cc and keep or replace Bcc, with an optional inline body

case-draft-change-clear-cc-body-file — Clear Cc and keep or replace Bcc, with the body read from a file

case-draft-change-clear-bcc-body — Clear Bcc and keep or replace Cc, with an optional inline body

case-draft-change-clear-bcc-body-file — Clear Bcc and keep or replace Cc, with the body read from a file

case-draft-change-clear-cc-bcc-body — Clear Cc and Bcc, with an optional inline body

case-draft-change-clear-cc-bcc-body-file — Clear Cc and Bcc, with the body read from a file

afmail case draft list

afmail case draft new

case-draft-new-to-inline-body — Visible recipient with an inline body or the default template

case-draft-new-to-body-file — Visible recipient with the body read from a file

case-draft-new-bcc-only-inline-body — Only blind recipients, with an inline body or the default template

case-draft-new-bcc-only-body-file — Only blind recipients, with the body read from a file

afmail case draft remove

afmail case draft reply

case-draft-reply-inline-body — Body given inline, or left to the default reply template

case-draft-reply-body-file — Body read from a file; the inline –body is absent here

afmail case draft review

afmail case draft send

afmail case draft show

afmail case draft upload

afmail case draft validate

afmail case list

case-list-active — List active cases; this is the default

case-list-archived — List archived cases only

case-list-all — List active and archived cases together

afmail case merge

afmail case move

afmail case notes append

afmail case notes replace

afmail case notes show

afmail case remove

afmail case rename

afmail case review

afmail case set-summary

afmail case show

afmail case suggestion clear

afmail case suggestion set

case-suggestion-set-archive — Suggest archiving this case

case-suggestion-set-unarchive — Suggest unarchiving this case into a group

case-suggestion-set-move — Suggest moving this case to another group

case-suggestion-set-rename — Suggest renaming this case

case-suggestion-set-tag — Suggest adding a tag

case-suggestion-set-untag — Suggest removing a tag

case-suggestion-set-trash — Suggest trashing every message in this case

case-suggestion-set-delete — Suggest deleting this case

afmail case tag

afmail case trash

afmail case unarchive

afmail case untag

afmail config add

afmail config get

afmail config remove

afmail config set

afmail config show

afmail contact create

afmail contact delete

afmail contact email add

afmail contact email remove

afmail contact extract

contact-extract-triage — Extract from triage messages; this is the default source

contact-extract-case — Extract from one case’s messages

contact-extract-all — Extract from every triage and case message

afmail contact list

afmail contact move

afmail contact notes append

afmail contact notes replace

afmail contact notes show

`afmail api export`

`afmail api serve`

`afmail case add`

`afmail case archive`

`afmail case create`

`afmail case delete`

`afmail case draft attach`

`afmail case draft change`

`case-draft-change-recipients-body` — Keep or replace Cc and Bcc, with an optional inline body

`case-draft-change-recipients-body-file` — Keep or replace Cc and Bcc, with the body read from a file

`case-draft-change-clear-cc-body` — Clear Cc and keep or replace Bcc, with an optional inline body

`case-draft-change-clear-cc-body-file` — Clear Cc and keep or replace Bcc, with the body read from a file

`case-draft-change-clear-bcc-body` — Clear Bcc and keep or replace Cc, with an optional inline body

`case-draft-change-clear-bcc-body-file` — Clear Bcc and keep or replace Cc, with the body read from a file

`case-draft-change-clear-cc-bcc-body` — Clear Cc and Bcc, with an optional inline body

`case-draft-change-clear-cc-bcc-body-file` — Clear Cc and Bcc, with the body read from a file

`afmail case draft list`

`afmail case draft new`

`case-draft-new-to-inline-body` — Visible recipient with an inline body or the default template

`case-draft-new-to-body-file` — Visible recipient with the body read from a file

`case-draft-new-bcc-only-inline-body` — Only blind recipients, with an inline body or the default template

`case-draft-new-bcc-only-body-file` — Only blind recipients, with the body read from a file

`afmail case draft remove`

`afmail case draft reply`

`case-draft-reply-inline-body` — Body given inline, or left to the default reply template

`case-draft-reply-body-file` — Body read from a file; the inline –body is absent here

`afmail case draft review`

`afmail case draft send`

`afmail case draft show`

`afmail case draft upload`

`afmail case draft validate`

`afmail case list`

`case-list-active` — List active cases; this is the default

`case-list-archived` — List archived cases only

`case-list-all` — List active and archived cases together

`afmail case merge`

`afmail case move`

`afmail case notes append`

`afmail case notes replace`

`afmail case notes show`

`afmail case remove`

`afmail case rename`

`afmail case review`

`afmail case set-summary`

`afmail case show`

`afmail case suggestion clear`

`afmail case suggestion set`

`case-suggestion-set-archive` — Suggest archiving this case

`case-suggestion-set-unarchive` — Suggest unarchiving this case into a group

`case-suggestion-set-move` — Suggest moving this case to another group

`case-suggestion-set-rename` — Suggest renaming this case

`case-suggestion-set-tag` — Suggest adding a tag

`case-suggestion-set-untag` — Suggest removing a tag

`case-suggestion-set-trash` — Suggest trashing every message in this case

`case-suggestion-set-delete` — Suggest deleting this case

`afmail case tag`

`afmail case trash`

`afmail case unarchive`

`afmail case untag`

`afmail config add`

`afmail config get`

`afmail config remove`

`afmail config set`

`afmail config show`

`afmail contact create`

`afmail contact delete`

`afmail contact email add`

`afmail contact email remove`

`afmail contact extract`

`contact-extract-triage` — Extract from triage messages; this is the default source

`contact-extract-case` — Extract from one case’s messages

`contact-extract-all` — Extract from every triage and case message

`afmail contact list`

`afmail contact move`

`afmail contact notes append`

`afmail contact notes replace`

`afmail contact notes show`

`afmail contact phone add`

`afmail contact phone remove`

`afmail contact rename`