Skip to content

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.

Start with a realistic local demo before connecting your own mail:

Terminal window
mxr demo --no-tui

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

Terminal window
mxr search "is:unread" --format json --limit 10

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

Terminal window
mxr demo stop

For Gmail on your local machine:

Terminal window
mxr accounts add gmail

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

Terminal window
mxr accounts add outlook

For a Microsoft 365 work or school account:

Terminal window
mxr accounts add outlook-work

For IMAP+SMTP non-interactively (e.g. Gmail with an app password):

Terminal window
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.com

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

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:

Terminal window
mxr sync # trigger, return immediately
mxr sync --wait # trigger, then wait for idle
mxr sync --wait --wait-timeout-secs 900 # a first backfill needs a longer wait

What 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 messages

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

Terminal window
mxr sync --status
mxr 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.

Terminal window
mxr

j/k to navigate, <Enter> to open, R for reader mode, Ctrl-p for the command palette, / for search, ? for help.

Terminal window
mxr web

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

Terminal window
# What needs you
mxr desk
# Search
mxr search "from:alice@example.com is:unread" --format json | jq .
# Read the first match
mxr cat <message-id>
# Reply and send
mxr reply <message-id> --body "On it." --yes
# Archive a query
mxr archive --search "label:newsletters older_than:30d" --dry-run
mxr archive --search "label:newsletters older_than:30d" --yes

Most read/list/status/mutation surfaces accept --format json; the generated CLI reference lists the exact formats per command.

Run into something? See Troubleshooting.