imap-cli

A command-line IMAP email client for fast, agent-driven email triage.

• Syncs email metadata + plaintext bodies from multiple IMAP accounts into a local SQLite database with full-text search (FTS5).
• Indexes attachments without downloading them — payloads are fetched on demand.
• Non-destructive: move and flag mail, never delete it.
• Pure Python standard library — zero runtime dependencies.

Installation

Requires Python 3.10+ and uv.

Install as a tool (adds imap-cli to your PATH):

uv tool install git+https://github.com/<you>/imap-cli   # from a repo
uv tool install .                                        # from a local clone

Or build a wheel and install it anywhere:

uv build
uv tool install dist/imap_cli-*.whl

Configuration

Accounts are defined in ~/.config/imap-cli/config.toml (override with $IMAP_CLI_CONFIG). Passwords are stored in plaintext, so restrict the file:

mkdir -p ~/.config/imap-cli
cp config.example.toml ~/.config/imap-cli/config.toml
chmod 600 ~/.config/imap-cli/config.toml

[accounts.work]
host = "imap.example.org"
username = "user@example.org"
password = "app-specific-password"
folders = ["INBOX", "Archive"]   # optional (default ["INBOX"])

Use an app-specific password where available; OAuth2-only providers are not supported.

Usage

Commands print JSON by default; add --human for readable output.

imap-cli accounts list
imap-cli sync --account work --since 2025-01-01
imap-cli search "invoice" --account work
imap-cli show 42                          # id comes from search/list
imap-cli attachment get 42 --part 2 --out ./invoice.pdf
imap-cli move 42 --to Archive

Run imap-cli --help for the full command reference.

Development

git clone <repo-url> && cd imap-cli
uv sync                                    # create the environment
uv run imap-cli --help                     # run without installing
uv run python -m unittest discover -s tests -v   # run the tests

See AGENTS.md for the architecture, module map, and coding conventions.

License

BSD 2-Clause — see LICENSE.