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.

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.

Global options

These work before or after the command name:

--json — emit machine-readable JSON instead of text.
--url URL — base URL of a running core (dev override).
--token-file PATH — read the API token from this file (dev override).
--verbose, -v — show core log output on stderr (-v INFO, -vv DEBUG).

Commands

Command	What it does
`start`	Start the core daemon (foreground; --detach for background).
`stop`	Stop the core daemon.
`restart`	Restart the core daemon.
`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).
`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 an account (or one folder) now.
`ask`	Answer a question from the mail, citing the messages.
`pipeline`	Pipeline status: stages, throughput, parked jobs.
`usage`	Model calls and tokens per workspace, stage and model.
`plugins`	List plugins; --check runs the health probe now.
`accounts`	The configured accounts (never credentials).
`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).
`agents`	Create, list and revoke external agents (the swarm).
`jobs`	Lease and finish jobs as an agent (OAKEN_AGENT_TOKEN).
`mcp`	Bridge an MCP client that speaks stdio to the MCP server in core.
`enrich`	Run or show the enrichers (summary, triage, actions, inspector) on a message.
`sieve`	Check, try and list Sieve filter scripts; refilter stored mail.
`admin`	Administration: add and inspect accounts.
`auth`	Store an account's credential (Gmail consent, SMTP or IMAP password).
`completion`	Print a shell completion script (bash, zsh or fish).

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.

Command details

`start`

Start the core daemon (foreground; --detach for background).

Options:

--detach — Run in the background.

`stop`

Stop the core daemon.

No arguments.

`restart`

Restart the core daemon.

Options:

--detach — Run in the background.

`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.

Arguments:

name — Operation name; omit to list operations.

Options:

--json-input — The operation input as a JSON object. Use '-' or omit to read stdin when piped.
--describe — Show the operation's summary and input and output fields instead of calling it.
--yes — Confirm a mutating operation (the person asked for exactly this).

`status`

Is core running? (does not start it)

No arguments.

`search`

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:

query — Search terms and operators.

Options:

--from — Only this sender.
--since — Only after this date (ISO 8601).
--before — Only before this date (ISO 8601).
--label — Only messages carrying this label.
--account — Restrict to one account.
--disposition — inbox, archive or discarded (discarded is explicit).
--category — Only this triage category.
--min-priority — Only this priority or more.
--unread — Only unread messages.
--keyword — Keyword search only (no model, no vectors).
--limit — Maximum results.

`show`

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

Arguments:

message_id — The message id.

Options:

--raw — Include the raw bytes (base64 in --json).
--headers — Show only the raw headers.

`summarize`

Summarize messages with the local model.

Arguments:

ID — One or more message ids.

Options:

--mark-read — Also mark the summarized messages read.

`read`

Mark messages read.

Arguments:

ID — One or more message ids.

Options:

--yes — Confirm a bulk change (>25 messages).

`unread`

Mark messages unread.

Arguments:

ID — One or more message ids.

Options:

--yes — Confirm a bulk change (>25 messages).

`undo`

Undo a read-state change from the audit log.

Arguments:

audit_id — The audit id to undo (see 'oaken audit').

`sync`

Sync an account (or one folder) now.

Options:

--account — Account to sync; default is all.
--folder — One folder; default is the whole account.
--wait — Wait until the sync job finishes.
--timeout — Give up waiting after S seconds.

`ask`

Answer a question from the mail, citing the messages.

Arguments:

question — The question to answer.

`pipeline`

Pipeline status: stages, throughput, parked jobs.

Arguments:

subcommand — status (default).

`usage`

Model calls and tokens per workspace, stage and model.

Options:

--since-hours — Only the last H hours of usage.
--workspace — Only this workspace.

`plugins`

List plugins; --check runs the health probe now.

Options:

--check — Run each plugin's health probe.

`accounts`

The configured accounts (never credentials).

No arguments.

`audit`

The newest audit-log rows.

Options:

--limit — How many rows (max 500).
--op — Only rows for this operation.

`operations`

Every operation with its permission and MCP exposure.

No arguments.

`reprocess`

Bring one pipeline stage up to date.

Arguments:

stage — The stage to reprocess.

Options:

--account — Restrict to one account.

`rebuild-index`

Rebuild the search index from the raw store.

Options:

--account — Restrict to one account.
--force — Re-index even where the content hash is unchanged.

`watch`

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

No arguments.

`agents`

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

`agents create`

Arguments:

label — A name for the agent.

Options:

--kind — A job kind it may lease.
--account — Limit it to this account (repeatable).
--max-leases — Jobs it may hold at once.
--max-per-hour — Jobs it may claim per hour.

`agents list`

List agents.

Options:

--all — Include revoked agents.

`agents revoke`

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

Arguments:

agent_id — The agent id (see 'oaken agents list').

`jobs`

The agent side of the queue. Authenticated by the agent's own token (OAKEN_AGENT_TOKEN or --agent-token-file); the API token is not used.

Options:

--agent-token-file — Read the agent token from PATH.

`jobs claim`

Lease the next job.

Options:

--kind — Only this kind.

`jobs heartbeat`

Extend a lease.

Arguments:

job_id —

`jobs complete`

Hand back a result.

Arguments:

job_id —

Options:

--result — The result object; '-' reads stdin.
--produced-by — The model or tool that made it.

`jobs fail`

Report an error.

Arguments:

job_id —

Options:

--error — What went wrong (no mail).
--permanent — Do not retry it.

`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'.

Options:

--timeout — Give up on a call after.
--agent — Speak to the swarm door as an agent (token from OAKEN_AGENT_TOKEN).
--agent-token-file — Read the agent token from a file.

`enrich`

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

`enrich run`

Run the enrichers on one message now.

Arguments:

message_id —
enricher — Only these enrichers (default: all).

Options:

--force — Run even if a current result is stored.

`enrich show`

Show the stored results.

Arguments:

message_id —
enricher — One enricher (default: all stored).

`sieve`

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

`sieve check`

Compile a script file.

Arguments:

file —

`sieve test`

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

Arguments:

file —

Options:

--message — A stored message.
--eml — A message file.

`sieve list`

The scripts core would load.

No arguments.

`sieve refilter`

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

Options:

--account — Restrict to one account.

`admin`

Administration: add and inspect accounts.

`admin account`

Mail accounts.

`admin account list`

List accounts.

No arguments.

`admin account show`

One account and its settings.

Arguments:

account_id —

`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 auth'. Give --provider, --id and --name (and --set) to skip the questions.

Options:

--provider — gmail, smtp or imap.
--id — a-z, 0-9, - and _.
--name — A display name.
--set — A provider setting (repeatable).

`auth`

gmail opens Google's consent and waits; smtp and imap read the password without echo. Nothing is ever printed, taken as an argument, or written to disk: the credential goes to the OS keyring.

Arguments:

provider —

Options:

--account — The account (default: the only one).
--check — Check the stored credential only.
--password-stdin — Read the password from one line of stdin.
--no-browser — Only print the Gmail address.
--timeout — Gmail: give up after S seconds.

`completion`

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

Arguments:

shell —