Quick start
After installing, use mxr to inspect synthetic mail on this computer. Then choose the CLI, web app, TUI, or an agent; they use the same local daemon.
1. Try the demo inbox
Section titled “1. Try the demo inbox”Start with a realistic local demo before connecting your own mail:
mxr demo --no-tuiThis creates a separate demo config, database, socket, and daemon. It seeds a two-account synthetic inbox. The demo profile is separate from your real profile and uses a canned model provider for model-assisted demo results. Those results demonstrate the workflow, not model quality.
The command reports progress and leaves the terminal available for local queries and other clients. To open the demo TUI, run mxr. The demo supports a smaller seed with mxr demo --messages 5000 --no-tui.
Demo mode is sticky. Subsequent mxr commands target the demo profile until you stop it. Keep it active for the following query and client choices. The TUI and web app show a DEMO marker; check the selected profile with mxr demo status.
Query local synthetic mail before choosing a client:
mxr search "is:unread" --format json --limit 10The result is local mailbox data. Open the browser client with mxr web, the TUI with mxr, or follow Use mxr with an existing agent. For the five mail modes and Now, continue to Work through your day.
mxr demo stop2. Add your account
Section titled “2. Add your account”For Gmail on your local machine:
mxr accounts add gmailThe wizard prompts for an account name and your Gmail address, then opens a browser to authorize. If you’re SSH’d into a remote box, see the Gmail setup notes on SSH-friendly flows.
For Outlook.com, Hotmail, or Live:
mxr accounts add outlookFor a Microsoft 365 work or school account:
mxr accounts add outlook-workFor IMAP+SMTP non-interactively (e.g. Gmail with an app password):
MXR_IMAP_PASSWORD="$APP_PASSWORD" MXR_SMTP_PASSWORD="$APP_PASSWORD" \ mxr accounts add imap-smtp \ --account-name personal \ --email you@gmail.com \ --imap-host imap.gmail.com \ --imap-username you@gmail.com \ --smtp-host smtp.gmail.com \ --smtp-username you@gmail.comMXR_IMAP_PASSWORD / MXR_SMTP_PASSWORD env vars resolve when stdin is not a TTY, which is handy for CI. You can also pass --imap-password / --smtp-password literal values if you don’t mind shell history.
3. Sync
Section titled “3. Sync”mxr sync starts a sync in the daemon and returns as soon as it has started. The account keeps syncing afterwards, so you can start reading mail right away. Add --wait to stay until that account reports idle:
mxr sync # trigger, return immediatelymxr sync --wait # trigger, then wait for idlemxr sync --wait --wait-timeout-secs 900 # a first backfill needs a longer waitWhat you get: with --wait, a live progress line on stderr each time the count moves, then exit 0 once the account is idle.
personal: 3,000/50,000 — Stored 3000 messagesThe denominator appears only when the provider can say how much is left. Gmail and IMAP cannot count the remainder without paying for it, so there you get a bare running count.
--wait also exits non-zero if the sync it started failed. An error the account was already carrying before the trigger does not count.
Check on it any time without waiting:
mxr sync --statusmxr sync --status --format json | jq '.[] | {account_name, sync_in_progress, progress}'Subsequent syncs are incremental and run automatically in the background once the daemon is up.
4. Open the TUI
Section titled “4. Open the TUI”mxrj/k to navigate, <Enter> to open, R for reader mode, Ctrl-p for the command palette, / for search, ? for help.
5. Or open the web app
Section titled “5. Or open the web app”mxr webThe web app opens on Now: the few things that need you now, from every mode, at most ten. The TUI opens on the same Now. Work through your day walks through it.
6. Or do it from the CLI
Section titled “6. Or do it from the CLI”# What needs youmxr desk
# Searchmxr search "from:alice@example.com is:unread" --format json | jq .
# Read the first matchmxr cat <message-id>
# Reply and sendmxr reply <message-id> --body "On it." --yes
# Archive a querymxr archive --search "label:newsletters older_than:30d" --dry-runmxr archive --search "label:newsletters older_than:30d" --yesMost read/list/status/mutation surfaces accept --format json; the generated CLI reference lists the exact formats per command.
What’s next
Section titled “What’s next”- Work through your day: Now, Messages, To do, Updates, Reading and Archive.
- Configure rules for declarative filing.
- Write a saved search for your daily inbox lens.
- Hand mxr to an LLM: the same CLI is the agent surface.
- Use mxr with an existing agent: connect local Codex with MCP or use the CLI skill.
Run into something? See Troubleshooting.