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.
`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 an account (or one folder) now.
`ask`	Answer a question from the mail, citing the messages.
`pipeline`	Pipeline status, and pausing the model-bound stages.
`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`	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, 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).
`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.

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.

`reload`

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

No arguments.

`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.
--offset — Skip this many (paging).
--starred — Only starred messages.
--has-attachment — Only messages with an attachment.

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

`thread`

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

Arguments:

message_id — Any message in the conversation.

Options:

--limit — Most messages to show.

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

Options:

--timeout — Give up waiting for the answer after S seconds (a local model can be slow).

`pipeline`

Default shows status. 'pause'/'resume' stop and restart the model-bound ingest stages (embed, enrich) — mail keeps landing and being filtered while paused. 'parked' re-queues failed ingest jobs.

Arguments:

subcommand — status (default), pause, resume, or parked.

Options:

--why — A note recorded with a pause.
--retry — With 'parked': re-queue this one parked job.
--all — With 'parked': re-queue every parked ingest job.

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

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:

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

`jobs list`

List jobs in the queue.

Options:

--status — Only jobs in this state.
--kind — Only this kind, e.g. ingest.enrich.
--account — Only this account.
--limit — How many (newest first, max 500).

`jobs show`

Show one job in full.

Arguments:

job_id —

`jobs cancel`

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

Arguments:

job_id —

`jobs retry`

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

Arguments:

job_id —

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

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

Arguments:

name — The script file name, e.g. 10-lists.sieve.

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

name — The script file name (e.g. 20-work.sieve).
file — The script file to read ('-' reads stdin).

Options:

--suggest-name — Print the next free NN-prefixed name and exit (give a base with --base).
--base — Base for --suggest-name (default filter).

`sieve delete`

Remove one script.

Arguments:

name — The script file name.

`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).
--receive-only — Listen but never send (the default for a new Gmail account until send is turned on).

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

Arguments:

account_id —

Options:

--set — A setting to change (repeatable).
--receive-only — Mark the account receive-only (listen but never send).
--can-send — Allow this account to be a send route (undo receive-only).

`admin account remove`

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

Arguments:

account_id —

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

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

`schedule list`

Every schedule and its state.

Options:

--crontab — Also print a read-only crontab export.

`schedule set`

Create or change a schedule.

Arguments:

account_id — The account to schedule.
schedule — 'every 15m' or a five-field cron expression (UTC-aware).

Options:

--folder — A per-folder schedule (default: account).
--timezone — e.g. America/New_York (unchanged if omitted).
--quiet — Mute alerts in this window; sync still runs.
--clear-quiet — Remove the quiet window.
--run-now — Also sync immediately.

`schedule pause`

Pause a schedule.

Arguments:

account_id — The account to schedule.

Options:

--folder — A per-folder schedule (default: account).
--why — A note recorded with the pause.

`schedule resume`

Resume a paused schedule.

Arguments:

account_id — The account to schedule.

Options:

--folder — A per-folder schedule (default: account).

`schedule remove`

Remove a schedule.

Arguments:

account_id — The account to schedule.

Options:

--folder — A per-folder schedule (default: account).

`completion`

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

Arguments:

shell —

`help`

Show this help, or help for one COMMAND.

Arguments:

COMMAND — A command to show help for.