# afmail CLI Reference
> Regenerate with `scripts/projects/agent-first-mail/generate-cli-doc.sh` (runs `afmail --help --recursive --output markdown`).
# afmail - Agent-First Mail: local-first email case workspace for agents.
Agent-First Mail: local-first email case workspace for agents.
### Interface Policy
- Files are the read interface; CLI is for effects.
- One workspace represents one mailbox account.
- Message commands use `afmail message ACTION MESSAGE_ID ...`.
- Case commands use `afmail case ACTION CASE_REF ...`.
- Active and archived cases are readable with `afmail case show REF` and
`afmail archive case show REF`.
- stdout carries structured Agent-First Data events; stderr is not a protocol channel.
### Workspace Shape
```text
.afmail/messages/ raw .eml plus durable remote sidecars
messages/ rebuildable parsed message cache
.afmail/logs/events.jsonl append-only audit log
.afmail/transactions/ transient local write transaction sentinels
.afmail/workspace.progress.json latest push/pull runtime snapshot
templates/ user-editable generated Markdown templates
triage/message_*.md active unprocessed message views
spam/*.md generated spam review views
trash/*.md generated trash review views
deleted/*.md generated remote-deleted review views
cases/<group>/<case_uid>-<name>/case.md generated case entry view
cases/<group>/<case_uid>-<name>/data/ canonical case state
cases/<group>/<case_uid>-<name>/views/ generated case detail views
archive/cases/<case_uid>-<name>/ archived case workspaces
archive/notifications/<archive_uid>-<name>/archive.md generated archive entry view
archive/notifications/<archive_uid>-<name>/data/ canonical archive state
archive/notifications/<archive_uid>-<name>/views/ generated archive detail views
```
### Examples
```text
afmail init
afmail init email-a
afmail skill status
afmail skill install --agent codex --scope project
afmail status
afmail doctor
afmail pull
afmail pull sent archive
afmail remote folders
afmail case create --name 应用反馈-肥料登记 --message message_inbox_607146690_21 --group open --reason "new feedback thread"
afmail case show c20260603001
afmail case add c20260603001 message_inbox_607146690_22 --reason "follow-up belongs to same feedback case"
afmail archive message create --name 服务通知 --message message_inbox_607146690_23 --summary "billing notification" --reason "billing notification"
afmail archive message show a20260603001
afmail archive message restore a20260603001 message_inbox_607146690_23 --reason "needs triage again"
afmail message spam message_inbox_607146690_23 --reason "phishing attempt"
afmail message trash message_inbox_607146690_24 --reason "duplicate no longer needed"
afmail render refresh
afmail doctor repair --confirm
afmail case move c20260603001 waiting
afmail case archive c20260603001 --reason "feedback handled"
afmail archive case restore c20260603001 --group open --reason "customer replied"
afmail case tag c20260603001 legal --reason "legal review needed"
afmail case draft reply c20260603001 message_inbox_607146690_22
afmail case draft attach c20260603001 reply-message_inbox_607146690_22.md ./screenshot.png
afmail case draft change c20260603001 reply-message_inbox_607146690_22.md --body "Thanks, I will check this."
afmail case draft validate c20260603001 reply-message_inbox_607146690_22.md
afmail case draft send c20260603001 reply-message_inbox_607146690_22.md
afmail case draft remove c20260603001 reply-message_inbox_607146690_22.md --reason "mistaken draft"
afmail push list
afmail push
afmail push --confirm
afmail purge
afmail purge spam --older-than-days 30
afmail purge deleted
afmail log list --limit 20
afmail message show message_inbox_607146690_21
afmail message attachment fetch message_inbox_607146690_21 2
```
### Exit Codes
- `0`: command completed successfully
- `1`: runtime/store/protocol error
- `2`: invalid CLI arguments
```text
Agent-First Mail: local-first email case workspace for agents.
### Interface Policy
- Files are the read interface; CLI is for effects.
- One workspace represents one mailbox account.
- Message commands use `afmail message ACTION MESSAGE_ID ...`.
- Case commands use `afmail case ACTION CASE_REF ...`.
- Active and archived cases are readable with `afmail case show REF` and
`afmail archive case show REF`.
- stdout carries structured Agent-First Data events; stderr is not a protocol channel.
### Workspace Shape
```text
.afmail/messages/ raw .eml plus durable remote sidecars
messages/ rebuildable parsed message cache
.afmail/logs/events.jsonl append-only audit log
.afmail/transactions/ transient local write transaction sentinels
.afmail/workspace.progress.json latest push/pull runtime snapshot
templates/ user-editable generated Markdown templates
triage/message_*.md active unprocessed message views
spam/*.md generated spam review views
trash/*.md generated trash review views
deleted/*.md generated remote-deleted review views
cases/<group>/<case_uid>-<name>/case.md generated case entry view
cases/<group>/<case_uid>-<name>/data/ canonical case state
cases/<group>/<case_uid>-<name>/views/ generated case detail views
archive/cases/<case_uid>-<name>/ archived case workspaces
archive/notifications/<archive_uid>-<name>/archive.md generated archive entry view
archive/notifications/<archive_uid>-<name>/data/ canonical archive state
archive/notifications/<archive_uid>-<name>/views/ generated archive detail views
```
### Examples
```text
afmail init
afmail init email-a
afmail skill status
afmail skill install --agent codex --scope project
afmail status
afmail doctor
afmail pull
afmail pull sent archive
afmail remote folders
afmail case create --name 应用反馈-肥料登记 --message message_inbox_607146690_21 --group open --reason "new feedback thread"
afmail case show c20260603001
afmail case add c20260603001 message_inbox_607146690_22 --reason "follow-up belongs to same feedback case"
afmail archive message create --name 服务通知 --message message_inbox_607146690_23 --summary "billing notification" --reason "billing notification"
afmail archive message show a20260603001
afmail archive message restore a20260603001 message_inbox_607146690_23 --reason "needs triage again"
afmail message spam message_inbox_607146690_23 --reason "phishing attempt"
afmail message trash message_inbox_607146690_24 --reason "duplicate no longer needed"
afmail render refresh
afmail doctor repair --confirm
afmail case move c20260603001 waiting
afmail case archive c20260603001 --reason "feedback handled"
afmail archive case restore c20260603001 --group open --reason "customer replied"
afmail case tag c20260603001 legal --reason "legal review needed"
afmail case draft reply c20260603001 message_inbox_607146690_22
afmail case draft attach c20260603001 reply-message_inbox_607146690_22.md ./screenshot.png
afmail case draft change c20260603001 reply-message_inbox_607146690_22.md --body "Thanks, I will check this."
afmail case draft validate c20260603001 reply-message_inbox_607146690_22.md
afmail case draft send c20260603001 reply-message_inbox_607146690_22.md
afmail case draft remove c20260603001 reply-message_inbox_607146690_22.md --reason "mistaken draft"
afmail push list
afmail push
afmail push --confirm
afmail purge
afmail purge spam --older-than-days 30
afmail purge deleted
afmail log list --limit 20
afmail message show message_inbox_607146690_21
afmail message attachment fetch message_inbox_607146690_21 2
```
### Exit Codes
- `0`: command completed successfully
- `1`: runtime/store/protocol error
- `2`: invalid CLI arguments
Usage: afmail [OPTIONS] [COMMAND]
Commands:
init Initialize the current directory or a child path as an afmail workspace
pull Read configured IMAP mailbox ids into local message files without changing remote mail
config Read or update local afmail configuration
remote Inspect remote IMAP state for configuring mailboxes
push Push queued local work or manage the local push queue
status Report workspace health, counts, and latest pull/push progress
doctor Check afmail workspace consistency without inspecting Git
purge Permanently delete old local spam, trash, and remote-deleted records
skill Manage the Agent-First Mail skill for Codex, Claude Code, and opencode
triage Inspect the triage queue
message Operate on any local message id
case Create a case or operate on an existing case ref
archive Inspect and manage archived cases and direct-message archive categories
render Rebuild generated read views from local workspace state
log Inspect the workspace audit log
help Print this message or the help of the given subcommand(s)
Options:
--output <OUTPUT>
Output format: json (default), yaml, plain
[default: json]
--log <LOG>
Log categories (comma-separated): startup, request, progress, retry
--verbose
Enable all log categories
-V, --version
Print structured version event
-h, --help
Print help. Add --recursive to expand every nested subcommand; add --output json|yaml|markdown to render this help in another format.
```
## afmail init - Initialize the current directory or a child path as an afmail workspace
```text
Initialize the current directory or a child path as an afmail workspace
Usage: init [PATH]
Arguments:
[PATH]
Optional workspace path to initialize under the current directory
Options:
-h, --help
Print help
```
## afmail pull - Read configured IMAP mailbox ids into local message files without changing remote mail
```text
Read configured IMAP mailbox ids into local message files without changing remote mail
Usage: pull [IDS]...
Arguments:
[IDS]...
Configured mailbox ids to pull. With none, pulls actions.pull.default_mailbox_ids
Options:
-h, --help
Print help
```
## afmail config - Read or update local afmail configuration
```text
Read or update local afmail configuration
Usage: config <COMMAND>
Commands:
show Show local .afmail/config.json
get Get one config key
set Set one config key. Multiple values become an array for array keys
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail config show - Show local .afmail/config.json
```text
Show local .afmail/config.json
Usage: show
Options:
-h, --help
Print help
```
### afmail config get - Get one config key
```text
Get one config key
Usage: get <KEY>
Arguments:
<KEY>
Options:
-h, --help
Print help
```
### afmail config set - Set one config key. Multiple values become an array for array keys
```text
Set one config key. Multiple values become an array for array keys
Usage: set <KEY> [VALUES]...
Arguments:
<KEY>
[VALUES]...
Options:
-h, --help
Print help
```
## afmail remote - Inspect remote IMAP state for configuring mailboxes
```text
Inspect remote IMAP state for configuring mailboxes
Usage: remote <COMMAND>
Commands:
test Test IMAP login using local config
folders List IMAP folders/mailboxes
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail remote test - Test IMAP login using local config
```text
Test IMAP login using local config
Usage: test
Options:
-h, --help
Print help
```
### afmail remote folders - List IMAP folders/mailboxes
```text
List IMAP folders/mailboxes
Usage: folders
Options:
-h, --help
Print help
```
## afmail push - Push queued local work or manage the local push queue
```text
Push queued local work or manage the local push queue
Usage: push [OPTIONS] [COMMAND]
Commands:
list List queued local push items
help Print this message or the help of the given subcommand(s)
Options:
--dry-run
Show planned push actions without IMAP/SMTP writes. This is the default
--confirm
Apply queued IMAP/SMTP effects
-h, --help
Print help
```
### afmail push list - List queued local push items
```text
List queued local push items
Usage: list
Options:
-h, --help
Print help
```
## afmail status - Report workspace health, counts, and latest pull/push progress
```text
Report workspace health, counts, and latest pull/push progress
Usage: status
Options:
-h, --help
Print help
```
## afmail doctor - Check afmail workspace consistency without inspecting Git
```text
Check afmail workspace consistency without inspecting Git
Usage: doctor [COMMAND]
Commands:
repair Repair only unambiguous afmail-generated state
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail doctor repair - Repair only unambiguous afmail-generated state
```text
Repair only unambiguous afmail-generated state
Usage: repair [OPTIONS]
Options:
--confirm
Apply repair actions. Without this flag, repair is refused
-h, --help
Print help
```
## afmail purge - Permanently delete old local spam, trash, and remote-deleted records
```text
Permanently delete old local spam, trash, and remote-deleted records
Usage: purge [OPTIONS] [COMMAND]
Commands:
spam Permanently delete old local spam records
trash Permanently delete old local trash records
deleted Permanently delete old local records whose remote message disappeared
help Print this message or the help of the given subcommand(s)
Options:
--older-than-days <DAYS>
Only purge messages in a discard state at least this many days ago. Defaults to 30
-h, --help
Print help
```
### afmail purge spam - Permanently delete old local spam records
```text
Permanently delete old local spam records
Usage: spam [OPTIONS]
Options:
--older-than-days <DAYS>
Only purge messages marked spam at least this many days ago. Defaults to 30
-h, --help
Print help
```
### afmail purge trash - Permanently delete old local trash records
```text
Permanently delete old local trash records
Usage: trash [OPTIONS]
Options:
--older-than-days <DAYS>
Only purge messages marked trash at least this many days ago. Defaults to 30
-h, --help
Print help
```
### afmail purge deleted - Permanently delete old local records whose remote message disappeared
```text
Permanently delete old local records whose remote message disappeared
Usage: deleted [OPTIONS]
Options:
--older-than-days <DAYS>
Only purge messages marked remote-deleted at least this many days ago. Defaults to 30
-h, --help
Print help
```
## afmail skill - Manage the Agent-First Mail skill for Codex, Claude Code, and opencode
```text
Manage the Agent-First Mail skill for Codex, Claude Code, and opencode
Usage: skill <COMMAND>
Commands:
status Show whether the Agent-First Mail skill is installed and valid
install Install the Agent-First Mail skill
uninstall Remove an afmail-managed Agent-First Mail skill
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail skill status - Show whether the Agent-First Mail skill is installed and valid
```text
Show whether the Agent-First Mail skill is installed and valid
Usage: status [OPTIONS]
Options:
--agent <AGENT>
Agent to manage. Defaults to all personal skill targets
Possible values:
- all: Manage every agent that supports the requested scope
- codex: Manage the Codex skill under $CODEX_HOME/skills or .agents/skills
- claude-code: Manage the Claude Code skill under ~/.claude/skills or .claude/skills
- opencode: Manage the opencode skill under ~/.config/opencode/skills or .opencode/skills
[default: all]
--scope <SCOPE>
Skill scope. Project scope installs under the current project's skill directory
Possible values:
- personal: Install under the user-level skills directory
- project: Install under the current project's skills directory
[default: personal]
--skills-dir <SKILLS_DIR>
Directory that contains skill folders. Requires an explicit single --agent
-h, --help
Print help (see a summary with '-h')
```
### afmail skill install - Install the Agent-First Mail skill
```text
Install the Agent-First Mail skill
Usage: install [OPTIONS]
Options:
--agent <AGENT>
Agent to manage. Defaults to all personal skill targets
Possible values:
- all: Manage every agent that supports the requested scope
- codex: Manage the Codex skill under $CODEX_HOME/skills or .agents/skills
- claude-code: Manage the Claude Code skill under ~/.claude/skills or .claude/skills
- opencode: Manage the opencode skill under ~/.config/opencode/skills or .opencode/skills
[default: all]
--scope <SCOPE>
Skill scope. Project scope installs under the current project's skill directory
Possible values:
- personal: Install under the user-level skills directory
- project: Install under the current project's skills directory
[default: personal]
--skills-dir <SKILLS_DIR>
Directory that contains skill folders. Requires an explicit single --agent
--force
Overwrite or remove an unmanaged Agent-First Mail skill at the target path
-h, --help
Print help (see a summary with '-h')
```
### afmail skill uninstall - Remove an afmail-managed Agent-First Mail skill
```text
Remove an afmail-managed Agent-First Mail skill
Usage: uninstall [OPTIONS]
Options:
--agent <AGENT>
Agent to manage. Defaults to all personal skill targets
Possible values:
- all: Manage every agent that supports the requested scope
- codex: Manage the Codex skill under $CODEX_HOME/skills or .agents/skills
- claude-code: Manage the Claude Code skill under ~/.claude/skills or .claude/skills
- opencode: Manage the opencode skill under ~/.config/opencode/skills or .opencode/skills
[default: all]
--scope <SCOPE>
Skill scope. Project scope installs under the current project's skill directory
Possible values:
- personal: Install under the user-level skills directory
- project: Install under the current project's skills directory
[default: personal]
--skills-dir <SKILLS_DIR>
Directory that contains skill folders. Requires an explicit single --agent
--force
Overwrite or remove an unmanaged Agent-First Mail skill at the target path
-h, --help
Print help (see a summary with '-h')
```
## afmail triage - Inspect the triage queue
```text
Inspect the triage queue
Usage: triage <COMMAND>
Commands:
list List compact untriaged message locators
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail triage list - List compact untriaged message locators
```text
List compact untriaged message locators
Usage: list
Options:
-h, --help
Print help
```
## afmail message - Operate on any local message id
```text
Operate on any local message id
Usage: message <COMMAND>
Commands:
show Show the full local message metadata, body text, and attachment metadata
spam Mark junk/phishing/malware/suspicious mail locally, show it under spam/, and queue a Junk move
trash Explicitly discard this message locally, show it under trash/, and queue a Trash move
restore Restore a message from spam, trash, or direct archive back to triage
attachment Fetch an attachment for this message
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail message show - Show the full local message metadata, body text, and attachment metadata
```text
Show the full local message metadata, body text, and attachment metadata
Usage: show <MESSAGE_ID>
Arguments:
<MESSAGE_ID>
Message id, for example message_inbox_607146690_22
Options:
-h, --help
Print help
```
### afmail message spam - Mark junk/phishing/malware/suspicious mail locally, show it under spam/, and queue a Junk move
```text
Mark junk/phishing/malware/suspicious mail locally, show it under spam/, and queue a Junk move
Usage: spam [OPTIONS] <MESSAGE_ID>
Arguments:
<MESSAGE_ID>
Message id, for example message_inbox_607146690_22
Options:
--reason <REASON>
Why this disposition is correct; required by default
-h, --help
Print help
```
### afmail message trash - Explicitly discard this message locally, show it under trash/, and queue a Trash move
```text
Explicitly discard this message locally, show it under trash/, and queue a Trash move
Usage: trash [OPTIONS] <MESSAGE_ID>
Arguments:
<MESSAGE_ID>
Message id, for example message_inbox_607146690_22
Options:
--reason <REASON>
Why this disposition is correct; required by default
-h, --help
Print help
```
### afmail message restore - Restore a message from spam, trash, or direct archive back to triage
```text
Restore a message from spam, trash, or direct archive back to triage
Usage: restore [OPTIONS] <MESSAGE_ID>
Arguments:
<MESSAGE_ID>
Message id, for example message_inbox_607146690_22
Options:
--reason <REASON>
Why this restore is correct; required by default
-h, --help
Print help
```
### afmail message attachment - Fetch an attachment for this message
```text
Fetch an attachment for this message
Usage: attachment <COMMAND>
Commands:
fetch Fetch one attachment by MIME part id, or all attachments when omitted
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
#### afmail message attachment fetch - Fetch one attachment by MIME part id, or all attachments when omitted
```text
Fetch one attachment by MIME part id, or all attachments when omitted
Usage: fetch <MESSAGE_ID> [PART_ID]
Arguments:
<MESSAGE_ID>
Message id, for example message_inbox_607146690_22
[PART_ID]
Options:
-h, --help
Print help
```
## afmail case - Create a case or operate on an existing case ref
```text
Create a case or operate on an existing case ref
Usage: case <COMMAND>
Commands:
create Create a new case and return its stable UID/ref
list List compact active case locators
show Show a case's case.md (active or archived) without changing workspace state
add Add a message to this existing case
move Move this case to another group
rename Rename this active case's human-readable name without changing its UID
notes Show or edit active case notes
archive Archive this active case
reopen Reopen this case as active work without changing its tags
tag Add a case organization tag
untag Remove a case organization tag
draft Create, edit, validate, queue, or remove local case drafts
merge Merge another case into this case
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail case create - Create a new case and return its stable UID/ref
```text
Create a new case and return its stable UID/ref
Usage: create [OPTIONS] --name <NAME>
Options:
--name <NAME>
Human-readable case name used in case.md and the directory suffix
--group <GROUP>
Destination group. Defaults to the configured default group
--message <MESSAGE>
Optional first message to add to the case
--summary <SUMMARY>
Short summary for the first message
--reason <REASON>
Why this case is being created
-h, --help
Print help
```
### afmail case list - List compact active case locators
```text
List compact active case locators
Usage: list
Options:
-h, --help
Print help
```
### afmail case show - Show a case's case.md (active or archived) without changing workspace state
```text
Show a case's case.md (active or archived) without changing workspace state
Usage: show <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
-h, --help
Print help
```
### afmail case add - Add a message to this existing case
```text
Add a message to this existing case
Usage: add [OPTIONS] <CASE_REF> <MESSAGE_ID>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<MESSAGE_ID>
Message id to add
Options:
--summary <SUMMARY>
Short summary for this message in the case
--reason <REASON>
Why this message belongs in this case; required by default
-h, --help
Print help
```
### afmail case move - Move this case to another group
```text
Move this case to another group
Usage: move <CASE_REF> <GROUP>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<GROUP>
Destination group
Options:
-h, --help
Print help
```
### afmail case rename - Rename this active case's human-readable name without changing its UID
```text
Rename this active case's human-readable name without changing its UID
Usage: rename [OPTIONS] --name <NAME> <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--name <NAME>
New human-readable case name
--reason <REASON>
Why this name better represents the case; required by default
-h, --help
Print help
```
### afmail case notes - Show or edit active case notes
```text
Show or edit active case notes
Usage: notes <COMMAND>
Commands:
show Show notes markdown
append Append text to notes markdown
replace Replace notes markdown with text
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
#### afmail case notes show - Show notes markdown
```text
Show notes markdown
Usage: show <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
-h, --help
Print help
```
#### afmail case notes append - Append text to notes markdown
```text
Append text to notes markdown
Usage: append --text <TEXT> <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--text <TEXT>
Markdown text to append
-h, --help
Print help
```
#### afmail case notes replace - Replace notes markdown with text
```text
Replace notes markdown with text
Usage: replace --text <TEXT> <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--text <TEXT>
Markdown text to write
-h, --help
Print help
```
### afmail case archive - Archive this active case
```text
Archive this active case
Usage: archive [OPTIONS] <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--reason <REASON>
Why this case is ready to archive; required by default
-h, --help
Print help
```
### afmail case reopen - Reopen this case as active work without changing its tags
```text
Reopen this case as active work without changing its tags
Usage: reopen [OPTIONS] <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--reason <REASON>
Why this case should be reopened; required by default
-h, --help
Print help
```
### afmail case tag - Add a case organization tag
```text
Add a case organization tag
Usage: tag [OPTIONS] <CASE_REF> <TAG>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<TAG>
Case organization tag
Options:
--reason <REASON>
Why this tag is useful; required by default
-h, --help
Print help
```
### afmail case untag - Remove a case organization tag
```text
Remove a case organization tag
Usage: untag [OPTIONS] <CASE_REF> <TAG>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<TAG>
Case organization tag
Options:
--reason <REASON>
Why this tag should be removed; required by default
-h, --help
Print help
```
### afmail case draft - Create, edit, validate, queue, or remove local case drafts
```text
Create, edit, validate, queue, or remove local case drafts
Usage: draft <COMMAND>
Commands:
new Scaffold a new outbound draft (not a reply) in this case
reply Scaffold a reply draft to a message, prefilled and quoting the original
change Change an existing editable draft in place
show Show an existing draft in a review-friendly JSON shape
validate Validate a draft under the case drafts directory
save Queue this draft to be saved to the remote Drafts mailbox
send Queue this draft to be sent and recorded in the case after push succeeds
attach Copy or reference a file and add it to a draft's attachments
remove Remove a local draft and any queued outbound item for it
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
#### afmail case draft new - Scaffold a new outbound draft (not a reply) in this case
```text
Scaffold a new outbound draft (not a reply) in this case
Usage: new [OPTIONS] --to <TO> --subject <SUBJECT> <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--to <TO>
Recipient address. Repeatable
--cc <CC>
Cc address. Repeatable
--subject <SUBJECT>
Draft subject
--body <BODY>
Draft body text
--body-file <BODY_FILE>
Path to a file whose contents become the draft body
-h, --help
Print help
```
#### afmail case draft reply - Scaffold a reply draft to a message, prefilled and quoting the original
```text
Scaffold a reply draft to a message, prefilled and quoting the original
Usage: reply [OPTIONS] <CASE_REF> <MESSAGE_ID>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<MESSAGE_ID>
Message id in this case to reply to
Options:
--body <BODY>
Draft body text. Replaces the default reply template when provided
--body-file <BODY_FILE>
Path to a file whose contents become the draft body
--all
Reply to all original recipients (To and Cc), not just the sender
-h, --help
Print help
```
#### afmail case draft change - Change an existing editable draft in place
```text
Change an existing editable draft in place
Usage: change [OPTIONS] <CASE_REF> <DRAFT_NAME>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<DRAFT_NAME>
Draft markdown file under the case drafts directory
Options:
--subject <SUBJECT>
Replacement subject
--to <TO>
Replacement To list. Repeatable; when provided it replaces all To recipients
--cc <CC>
Replacement Cc list. Repeatable; when provided it replaces all Cc recipients
--clear-cc
Clear all Cc recipients
--body <BODY>
Replacement draft body text
--body-file <BODY_FILE>
Path to a file whose contents replace the draft body
-h, --help
Print help
```
#### afmail case draft show - Show an existing draft in a review-friendly JSON shape
```text
Show an existing draft in a review-friendly JSON shape
Usage: show <CASE_REF> <DRAFT_NAME>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<DRAFT_NAME>
Draft markdown file under the case drafts directory
Options:
-h, --help
Print help
```
#### afmail case draft validate - Validate a draft under the case drafts directory
```text
Validate a draft under the case drafts directory
Usage: validate <CASE_REF> <DRAFT_NAME>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<DRAFT_NAME>
Draft markdown file under the case drafts directory
Options:
-h, --help
Print help
```
#### afmail case draft save - Queue this draft to be saved to the remote Drafts mailbox
```text
Queue this draft to be saved to the remote Drafts mailbox
Usage: save <CASE_REF> <DRAFT_NAME>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<DRAFT_NAME>
Draft markdown file under the case drafts directory
Options:
-h, --help
Print help
```
#### afmail case draft send - Queue this draft to be sent and recorded in the case after push succeeds
```text
Queue this draft to be sent and recorded in the case after push succeeds
Usage: send <CASE_REF> <DRAFT_NAME>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<DRAFT_NAME>
Draft markdown file under the case drafts directory
Options:
-h, --help
Print help
```
#### afmail case draft attach - Copy or reference a file and add it to a draft's attachments
```text
Copy or reference a file and add it to a draft's attachments
Usage: attach <CASE_REF> <DRAFT_NAME> <PATH>
Arguments:
<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
Options:
-h, --help
Print help
```
#### afmail case draft remove - Remove a local draft and any queued outbound item for it
```text
Remove a local draft and any queued outbound item for it
Usage: remove [OPTIONS] <CASE_REF> <DRAFT_NAME>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
<DRAFT_NAME>
Draft markdown file under the case drafts directory
Options:
--reason <REASON>
Why this draft should be removed; required by default
-h, --help
Print help
```
### afmail case merge - Merge another case into this case
```text
Merge another case into this case
Usage: merge [OPTIONS] <CASE_REF> <OTHER_CASE_REF>
Arguments:
<CASE_REF>
Primary case ref
<OTHER_CASE_REF>
Case ref to merge into the primary case
Options:
--reason <REASON>
Why these cases should be merged; required by default
-h, --help
Print help
```
## afmail archive - Inspect and manage archived cases and direct-message archive categories
```text
Inspect and manage archived cases and direct-message archive categories
Usage: archive <COMMAND>
Commands:
list List compact archived cases and/or direct-message archive categories
message Operate on a direct-message archive category
case Operate on an archived case
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail archive list - List compact archived cases and/or direct-message archive categories
```text
List compact archived cases and/or direct-message archive categories
Usage: list [COMMAND]
Commands:
cases List compact archived cases
messages List compact direct-message archive categories
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
#### afmail archive list cases - List compact archived cases
```text
List compact archived cases
Usage: cases
Options:
-h, --help
Print help
```
#### afmail archive list messages - List compact direct-message archive categories
```text
List compact direct-message archive categories
Usage: messages
Options:
-h, --help
Print help
```
### afmail archive message - Operate on a direct-message archive category
```text
Operate on a direct-message archive category
Usage: message <COMMAND>
Commands:
create Create a direct-message archive category and optionally file one message
add File an existing message into this direct-message archive category
show Show archive category index and entries
restore Restore a direct archived message to triage
move Move a direct archived message to another archive category
rename Rename this archive category's human-readable name without changing its UID
set-summary Set or replace one direct archive entry summary
notes Show or edit archive category notes
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
#### afmail archive message create - Create a direct-message archive category and optionally file one message
```text
Create a direct-message archive category and optionally file one message
Usage: create [OPTIONS] --name <NAME>
Options:
--name <NAME>
Human-readable archive category name used in metadata and the directory suffix
--message <MESSAGE>
Optional message to immediately file into the new archive category
--summary <SUMMARY>
Required when --message is supplied
--reason <REASON>
Why this archive category is being created
-h, --help
Print help
```
#### afmail archive message add - File an existing message into this direct-message archive category
```text
File an existing message into this direct-message archive category
Usage: add [OPTIONS] --summary <SUMMARY> <ARCHIVE_REF> <MESSAGE_ID>
Arguments:
<ARCHIVE_REF>
Direct-message archive category ref: aYYYYMMDDNNN or aYYYYMMDDNNN-any-suffix
<MESSAGE_ID>
Message id to file
Options:
--summary <SUMMARY>
Human/agent-authored summary for this archive entry
--reason <REASON>
Why this disposition is correct; required by default
-h, --help
Print help
```
#### afmail archive message show - Show archive category index and entries
```text
Show archive category index and entries
Usage: show <ARCHIVE_REF>
Arguments:
<ARCHIVE_REF>
Direct-message archive category ref: aYYYYMMDDNNN or aYYYYMMDDNNN-any-suffix
Options:
-h, --help
Print help
```
#### afmail archive message restore - Restore a direct archived message to triage
```text
Restore a direct archived message to triage
Usage: restore [OPTIONS] <ARCHIVE_REF> <MESSAGE_ID>
Arguments:
<ARCHIVE_REF>
Direct-message archive category ref: aYYYYMMDDNNN or aYYYYMMDDNNN-any-suffix
<MESSAGE_ID>
Options:
--reason <REASON>
Why this message needs active triage again; required by default
-h, --help
Print help
```
#### afmail archive message move - Move a direct archived message to another archive category
```text
Move a direct archived message to another archive category
Usage: move [OPTIONS] <ARCHIVE_REF> <MESSAGE_ID> <NEW_ARCHIVE_REF>
Arguments:
<ARCHIVE_REF>
Source direct-message archive category ref
<MESSAGE_ID>
<NEW_ARCHIVE_REF>
Destination archive category ref
Options:
--reason <REASON>
Why this category is better; required by default
-h, --help
Print help
```
#### afmail archive message rename - Rename this archive category's human-readable name without changing its UID
```text
Rename this archive category's human-readable name without changing its UID
Usage: rename [OPTIONS] --name <NAME> <ARCHIVE_REF>
Arguments:
<ARCHIVE_REF>
Direct-message archive category ref: aYYYYMMDDNNN or aYYYYMMDDNNN-any-suffix
Options:
--name <NAME>
New human-readable archive name
--reason <REASON>
Why this name better represents the category; required by default
-h, --help
Print help
```
#### afmail archive message set-summary - Set or replace one direct archive entry summary
```text
Set or replace one direct archive entry summary
Usage: set-summary [OPTIONS] --summary <SUMMARY> <ARCHIVE_REF> <MESSAGE_ID>
Arguments:
<ARCHIVE_REF>
Direct-message archive category ref: aYYYYMMDDNNN or aYYYYMMDDNNN-any-suffix
<MESSAGE_ID>
Options:
--summary <SUMMARY>
--reason <REASON>
Why this summary is useful; required by default
-h, --help
Print help
```
#### afmail archive message notes - Show or edit archive category notes
```text
Show or edit archive category notes
Usage: notes <COMMAND>
Commands:
show Show notes markdown
append Append text to notes markdown
replace Replace notes markdown with text
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
##### afmail archive message notes show - Show notes markdown
```text
Show notes markdown
Usage: show <ARCHIVE_REF>
Arguments:
<ARCHIVE_REF>
Direct-message archive category ref: aYYYYMMDDNNN or aYYYYMMDDNNN-any-suffix
Options:
-h, --help
Print help
```
##### afmail archive message notes append - Append text to notes markdown
```text
Append text to notes markdown
Usage: append --text <TEXT> <ARCHIVE_REF>
Arguments:
<ARCHIVE_REF>
Direct-message archive category ref: aYYYYMMDDNNN or aYYYYMMDDNNN-any-suffix
Options:
--text <TEXT>
Markdown text to append
-h, --help
Print help
```
##### afmail archive message notes replace - Replace notes markdown with text
```text
Replace notes markdown with text
Usage: replace --text <TEXT> <ARCHIVE_REF>
Arguments:
<ARCHIVE_REF>
Direct-message archive category ref: aYYYYMMDDNNN or aYYYYMMDDNNN-any-suffix
Options:
--text <TEXT>
Markdown text to write
-h, --help
Print help
```
### afmail archive case - Operate on an archived case
```text
Operate on an archived case
Usage: case <COMMAND>
Commands:
show Show the archived case
restore Restore an archived case to an active case group
rename Rename this archived case's human-readable name without changing its UID
notes Show or edit archived case notes
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
#### afmail archive case show - Show the archived case
```text
Show the archived case
Usage: show <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
-h, --help
Print help
```
#### afmail archive case restore - Restore an archived case to an active case group
```text
Restore an archived case to an active case group
Usage: restore [OPTIONS] --group <GROUP> <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--group <GROUP>
Active case group to restore into
--reason <REASON>
Why this case needs active attention again; required by default
-h, --help
Print help
```
#### afmail archive case rename - Rename this archived case's human-readable name without changing its UID
```text
Rename this archived case's human-readable name without changing its UID
Usage: rename [OPTIONS] --name <NAME> <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--name <NAME>
New human-readable case name
--reason <REASON>
Why this name better represents the case; required by default
-h, --help
Print help
```
#### afmail archive case notes - Show or edit archived case notes
```text
Show or edit archived case notes
Usage: notes <COMMAND>
Commands:
show Show notes markdown
append Append text to notes markdown
replace Replace notes markdown with text
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
##### afmail archive case notes show - Show notes markdown
```text
Show notes markdown
Usage: show <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
-h, --help
Print help
```
##### afmail archive case notes append - Append text to notes markdown
```text
Append text to notes markdown
Usage: append --text <TEXT> <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--text <TEXT>
Markdown text to append
-h, --help
Print help
```
##### afmail archive case notes replace - Replace notes markdown with text
```text
Replace notes markdown with text
Usage: replace --text <TEXT> <CASE_REF>
Arguments:
<CASE_REF>
Case ref: cYYYYMMDDNNN or cYYYYMMDDNNN-any-suffix
Options:
--text <TEXT>
Markdown text to write
-h, --help
Print help
```
## afmail render - Rebuild generated read views from local workspace state
```text
Rebuild generated read views from local workspace state
Usage: render <COMMAND>
Commands:
refresh Rebuild generated case and direct-message archive read views
templates Export built-in language templates, keeping existing files unless forced
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail render refresh - Rebuild generated case and direct-message archive read views
```text
Rebuild generated case and direct-message archive read views
Usage: refresh
Options:
-h, --help
Print help
```
### afmail render templates - Export built-in language templates, keeping existing files unless forced
```text
Export built-in language templates, keeping existing files unless forced
Usage: templates [OPTIONS]
Options:
--force
Overwrite existing workspace templates with built-in defaults
-h, --help
Print help
```
## afmail log - Inspect the workspace audit log
```text
Inspect the workspace audit log
Usage: log <COMMAND>
Commands:
list List recent audit events
tail Tail recent audit events as JSON data
message List events for one message id
case List events for one case id
archive List events for one archive category
help Print this message or the help of the given subcommand(s)
Options:
-h, --help
Print help
```
### afmail log list - List recent audit events
```text
List recent audit events
Usage: list [OPTIONS]
Options:
--limit <LIMIT>
Maximum number of events to return
[default: 50]
-h, --help
Print help
```
### afmail log tail - Tail recent audit events as JSON data
```text
Tail recent audit events as JSON data
Usage: tail
Options:
-h, --help
Print help
```
### afmail log message - List events for one message id
```text
List events for one message id
Usage: message <MESSAGE_ID>
Arguments:
<MESSAGE_ID>
Options:
-h, --help
Print help
```
### afmail log case - List events for one case id
```text
List events for one case id
Usage: case <CASE_UID>
Arguments:
<CASE_UID>
Options:
-h, --help
Print help
```
### afmail log archive - List events for one archive category
```text
List events for one archive category
Usage: archive <ARCHIVE_UID>
Arguments:
<ARCHIVE_UID>
Options:
-h, --help
Print help
```