OAKENMAIL
Generated

CLI

Every `oaken` command, its options and the exit codes — generated by walking the real command-line parser.

The oaken command is a thin client over the local core: every command is one call to a registry operation. It holds no logic of its own, so a new operation is reachable immediately through the generic oaken operation NAME fallback, with no new release. oaken operation NAME takes the operation's own fields as flags (--describe lists them), and oaken PLUGIN VERB is shorthand for oaken operation PLUGIN.VERB, so a function a plugin offers is a command the moment it is installed.

Output is human-readable by default; --json gives the machine form on stdout (never sanitized — it is the contract a script reads), while logs and errors go to stderr. Text printed to a terminal is stripped of control and escape sequences, because mail is untrusted.

1

Global options

These work before or after the command name:

2

Commands

Command What it does
start Start the core daemon (in the background; --fg to stay attached).
stop Stop the core daemon, killing it if it will not stop in time.
restart Restart the core daemon (in the background; --fg to stay attached).
reload Make the running core re-read config.toml, without a restart.
operation Call any registry operation by name (generic fallback).
status Is core running? (does not start it)
search Search the mail (keyword and meaning, merged).
show Show one message (cleaned text, or --raw/--headers).
thread Show a conversation as a tree: who replied to whom (* marks unread).
summarize Summarize messages with the local model.
read Mark messages read.
unread Mark messages unread.
undo Undo a read-state change from the audit log.
sync Sync every account on every provider now (or one account, or one folder).
label Label messages (tags for finding mail).
folder File messages into folders under Inbox.
star Star messages (written back to the mailbox where it can be).
unstar Remove the star from messages.
mailbox Look at a mailbox: the folder tree, counts, a listing, or why a message is filed.
pipeline Pipeline status, and pausing the model-bound stages.
usage Model calls and tokens per workspace, stage and model.
plugins List plugins, and control one: enable, disable, reload, config, check, set.
config Show, test, save or reload config.toml through core.
accounts The configured accounts (never credentials).
workspaces List, inspect, create, edit and remove AI workspaces.
audit The newest audit-log rows.
operations Every operation with its permission and MCP exposure.
reprocess Bring one pipeline stage up to date.
rebuild-index Rebuild the search index from the raw store.
watch Stream core events as lines (or --json).
settings Show, check or change core's own settings (index, retrieval, ai, sync, ...).
storage Where the data is and how big it is.
vacuum Give back the space deleted mail left in the databases.
cache The enrichment cache: how it is doing, or clear it.
events Recent events from core's event log (--follow keeps watching).
trace Watch what a plugin or a job is told, thinks and returns (opt-in; holds mail text).
agents Create, list and revoke external agents (the swarm).
jobs The durable job queue: list, show, cancel, retry; or work it as an agent.
mcp Bridge an MCP client that speaks stdio to the MCP server in core.
enrich Run or show the enrichers (summary, actions, inspector) on a message.
triage Run, show or dry-run triage (the verdict that rates a message) on a message.
action Show what the actions did about a message, or approve one that is waiting.
sieve Check, try and list Sieve filter scripts; refilter stored mail.
admin Administration: add and inspect accounts.
schedule The per-account sync schedule: list, set, pause, resume, remove.
completion Print a shell completion script (bash, zsh or fish).
help Show this help, or help for one COMMAND.
3

Shortcuts

Three more commands each take a slice of the ones above: mill sync is not a command, sawyer sync is. oaken always takes them all.

Shortcut What it covers Commands
mill The Oaken core daemon: run it, configure it, look after its storage. start · stop · restart · reload · status · plugins · config · settings · storage · vacuum · cache · events · mcp · help
sawyer The Oaken mail flow: sync, the ingest pipeline, its jobs and schedules. sync · pipeline · reprocess · rebuild-index · watch · jobs · enrich · schedule · help
cubby The Oaken mailbox: search, read and file your mail. search · show · thread · summarize · read · unread · undo · label · folder · star · unstar · mailbox · sieve · help
4

Exit codes

Code Meaning When
0 ok The command succeeded.
1 error The operation ran and failed, or an unexpected error.
2 usage Bad arguments.
3 core down Core is not running — start it with "oaken start".
4 auth A bad API token, or a provider that needs re-authorizing.
5 needs confirmation A mutation returned a proposal and was not confirmed.
5

Command details

start

Start the core daemon (in the background; --fg to stay attached).

Options:

stop

Asks core to stop, waits for it to finish what it is doing (up to --grace seconds), and kills it if it is still running. Core's work is a durable queue, so a killed core loses nothing: unfinished jobs are retried when it starts again.

Options:

restart

Restart the core daemon (in the background; --fg to stay attached).

Options:

reload

Signals the running core (SIGHUP) to re-read its configuration and rebuild itself in the same process. An invalid file changes nothing.

Options:

operation

Call a registry operation directly. The input is JSON on --json-input or stdin. This reaches every operation the daemon offers, including ones added after this CLI was released. 'oaken operation' with no name lists the operations. The operation's own fields can be given as flags built from its input schema (see --describe), e.g. 'oaken operation list_messages --limit 5'; 'oaken PLUGIN VERB' is a shorthand for 'oaken operation PLUGIN.VERB'.

Arguments:

Options:

status

Is core running? (does not start it)

Options:

Hybrid search: keyword and vector results merged by rank. Operators in the query: from:, before:, after:, label:, in:, -term, "phrase", term*. Each hit says which retriever found it; if the vector side was down the result says so.

Arguments:

Options:

show

Show one message (cleaned text, or --raw/--headers).

Arguments:

Options:

thread

Show a conversation as a tree: who replied to whom (* marks unread).

Arguments:

Options:

summarize

Summarize messages with the local model.

Arguments:

Options:

read

Mark messages read.

Arguments:

Options:

unread

Mark messages unread.

Arguments:

Options:

undo

Undo a read-state change from the audit log.

Arguments:

Options:

sync

Sync every account on every provider now (or one account, or one folder).

Options:

label

Label messages (tags for finding mail).

oaken label list | create NAME | add NAME ID... | remove NAME ID...

Arguments:

Options:

folder

File messages into folders under Inbox.

oaken folder list | create PATH | add PATH ID... (or move) | remove ID... (back to the Inbox)

Arguments:

Options:

star

Star messages (written back to the mailbox where it can be).

oaken star list | add ID... | remove ID... (oaken unstar ID... is remove)

Arguments:

Options:

unstar

Remove the star from messages.

Arguments:

Options:

mailbox

tree (default): Inbox, folders, labels and Discarded with counts. counts: the sidebar's numbers. messages: list what is in a folder or under a label. rules ID: the labels and flags on a message and the Sieve rule behind each. --account limits counts and messages to one account.

Arguments:

Options:

pipeline

Default shows status. 'pause'/'resume' stop and restart the model-bound ingest stages (embed, triage, enrich), or just one (oaken pipeline pause enrich, or one enricher: enrich.summary) — mail keeps landing and being filtered while paused. 'limits enrich 2' changes how many jobs a stage runs at once, live. 'parked' re-queues failed ingest jobs.

Arguments:

Options:

usage

Model calls and tokens per workspace, stage and model.

Options:

plugins

Plugin control is core's, all here. Default lists plugins; --check runs the health probe now. 'disable' stops a plugin until 'enable' (or a restart; enabled = false in [plugins.KIND.NAME] makes it last). 'reload' restarts one on the current config.toml. 'config NAME' shows its settings. 'set NAME KEY=VALUE ...' changes them (--unset KEY, --replace, or --file FILE for TOML; comments in config.toml are kept, secrets are refused). 'check NAME [KEY=VALUE ...]' tries settings on a throwaway instance and writes nothing.

Arguments:

Options:

config

'show' prints config.toml. 'test FILE' checks an edit without saving it, 'save FILE' validates and saves it (the old file is kept as a timestamped .bak), 'reload' applies the saved file to the running core. FILE may be - for standard input.

Arguments:

Options:

accounts

The configured accounts (never credentials).

Options:

workspaces

Workspaces are named confidentiality levels: each has a trust level (secure or insecure) and an LLM backend. A secure workspace only uses a local backend. Default lists workspaces. 'get NAME' shows one. 'check NAME [TOML...]' validates without saving. 'set NAME [TOML...] [--file FILE]' creates or replaces. 'remove NAME' removes it (default cannot be removed).

Arguments:

Options:

audit

The newest audit-log rows.

Options:

operations

Every operation with its permission and MCP exposure.

Options:

reprocess

Bring one pipeline stage up to date.

Arguments:

Options:

rebuild-index

Rebuild the search index from the raw store.

Options:

watch

Stream core events as lines (or --json).

Options:

settings

'settings' lists every section; 'settings SECTION' one. 'settings set SECTION KEY=VALUE ...' saves a change (--unset KEY goes back to the default) to config.toml, keeping its comments; 'settings check ...' tests it without saving. Saved settings reach core on 'oaken reload' (or add --reload); the answer says which need more. An environment variable that overrides a key is reported.

Arguments:

Options:

storage

Where the data is and how big it is.

Options:

vacuum

Rewrites raw.db and index.db. One at a time, and not while an index rebuild runs. It holds each database's write lock while it works (ingest waits, reads go on) and needs about the database's own size free on the disk.

Options:

cache

'cache' (or 'cache stats') shows what it holds and how often it saved a model call. 'cache clear' deletes cached answers (--task TASK for one task): mail and the index are untouched, and cleared answers are recomputed on demand.

Arguments:

Options:

events

What core published recently, including before it was last restarted: ids, states and numbers, never mail text. --follow prints the history and then the live stream.

Options:

trace

The trace records, with the full text, what core hands a model and what it answers (the prompt, the thinking, the timings), the calls into every plugin, and what an agent claims and commits. It is off until oaken trace on (or [log] trace = true). oaken trace -f plugin.triager.ai follows one plugin (plugin.enricher.summary, plugin.llm_backend.ollama, ...); --job ID follows one job and nothing else.

Arguments:

Options:

agents

Agents lease jobs from the queue with a token of their own (the swarm page).

Options:

agents create

Register an agent and print its token once.

Arguments:

Options:

agents list

List agents.

Options:

agents revoke

Revoke an agent; its jobs go back on the queue.

Arguments:

Options:

jobs

Inspect and steer the durable queue (list, show, cancel, retry) with your API token. The agent protocol (claim, heartbeat, complete, fail) is authenticated by the agent's own token (OAKEN_AGENT_TOKEN or --agent-token-file) instead.

Options:

jobs list

List jobs in the queue.

Options:

jobs show

Show one job in full.

Arguments:

Options:

jobs cancel

Cancel a queued job (or ask a running one to stop).

Arguments:

Options:

jobs retry

Re-queue a failed or cancelled job to run now.

Arguments:

Options:

jobs claim

Lease the next job.

Options:

jobs heartbeat

Extend a lease.

Arguments:

Options:

jobs complete

Hand back a result.

Arguments:

Options:

jobs fail

Report an error.

Arguments:

Options:

mcp

Reads MCP messages on stdin and forwards them to the MCP server inside the running core, writing its answers to stdout. It adds nothing: the tools, the confirmation step and the limits are core's. If core is not running, tool calls answer with a core_not_running error. It never starts core. Point a stdio-only client (Claude Desktop) at 'oaken mcp'. 'oaken mcp expose' lists which operations MCP clients may call; 'oaken mcp expose NAME on|off|default' (--plugin for a plugin's operations) changes it.

Arguments:

Options:

enrich

Run or show the enrichers (summary, actions, inspector) on a message.

Options:

enrich run

Run the enrichers on one message now.

Arguments:

Options:

enrich show

Show the stored results.

Arguments:

Options:

triage

Run, show or dry-run triage (the verdict that rates a message) on a message.

Options:

triage run

Run the triagers on one message now.

Arguments:

Options:

triage show

Show the stored verdict.

Arguments:

Options:

triage try

Dry-run triage on a message or on text: the verdict, nothing stored.

Arguments:

Options:

action

Show what the actions did about a message, or approve one that is waiting.

Options:

action show

What each action did.

Arguments:

Options:

action approve

Say yes to an action that is waiting.

Arguments:

Options:

sieve

Scripts are files you edit; these commands never change them.

Options:

sieve check

Compile a script file.

Arguments:

Options:

sieve test

Run a script on one message and show each effect. Stores nothing.

Arguments:

Options:

sieve list

The scripts core would load.

Options:

sieve get

Print one script's text (to edit it).

Arguments:

Options:

sieve save

Compiles the script first and writes it only if it compiles, atomically and owner-only. Run order is by name, so a new script is best named NN-name.sieve; 'oaken sieve save --suggest-name' prints the next free NN.

Arguments:

Options:

sieve delete

Remove one script.

Arguments:

Options:

sieve refilter

Re-run the scripts over stored mail (a job).

Options:

admin

Administration: add and inspect accounts.

Options:

admin account

Mail accounts.

Options:

admin account list

List accounts.

Options:

admin account show

One account and its settings.

Arguments:

Options:

admin account add

Asks for the provider, an id, a name and the provider's own non-secret settings, then stores them. The credential is stored afterwards with 'oaken PROVIDER auth'. Give --provider, --id and --name (and --set) to skip the questions.

Options:

admin account set

Merges --set KEY=VALUE into the account's config and/or flips the receive-only switch. Credentials are never set here (use 'oaken PROVIDER auth').

Arguments:

Options:

admin account remove

Remove an account and its schedules (stored mail is kept).

Arguments:

Options:

schedule

When each account syncs. 'set' takes 'every 15m' or a five-field cron expression; edits are audited and take effect live. Editing a schedule is never offered over MCP.

Options:

schedule list

Every schedule and its state.

Options:

schedule set

Create or change a schedule.

Arguments:

Options:

schedule pause

Pause a schedule.

Arguments:

Options:

schedule resume

Resume a paused schedule.

Arguments:

Options:

schedule remove

Remove a schedule.

Arguments:

Options:

completion

Install with, for example: eval "$(oaken completion bash)".

Arguments:

help

Show this help, or help for one COMMAND.

Arguments: