Terminal email client with vim-style keybindings

Why Epist • Quick Start • Keybindings • Commands • Configuration • Comparison

Epist is a keyboard-driven email client for the terminal, built with Glyph. Gmail OAuth + IMAP/SMTP, two-column layout, threaded conversations — manage your inbox without leaving the terminal.

_{Inbox view — email list on the left, full message on the right}

Built for people who live in the terminal and want email to feel like vim, not like a web browser.

• Vim keybindings — j/k, gg/G, h/l, / to search, : for commands. Feels like home.
• Two-column layout — email list on the left, full view on the right. No pane juggling.
• Gmail + IMAP/SMTP — Gmail OAuth with PKCE and generic IMAP/SMTP. Use any provider, mix both.
• Secure credentials — password_command integration with Keychain, pass, 1Password CLI, Bitwarden, env vars.
• Threads & labels — conversation threading with [/], Gmail labels with colored dots, collapsible categories.
• Two-step search — instant local filtering + remote search with debouncing.
• Compose & reply — full compose, reply, reply-all, forward, and quick inline reply with contact autocomplete.
• Attachments & calendar — view/save/open attachments, parse .ics invites with RSVP support.
• Bulk actions & undo — select multiple threads with x, act on many, undo with z.
• Command palette — fuzzy-matched command bar (:) and context-aware help (?).
• Local-first — SQLite cache, instant startup, your data stays yours.
• Themeable — customize colors via TOML configuration.

Full comparison with other terminal email clients →

brew tap semos-labs/tap brew install epist

git clone https://github.com/semos-labs/epist.git cd epist && bun install bun dev # development bun start # production

Epist supports Gmail (OAuth) and IMAP/SMTP (any email provider). You can use both simultaneously.

Add your account to ~/.config/epist/config.toml:

[[accounts]] name = "Work" email = "me@work.com" provider = "imap" [accounts.imap] host = "imap.work.com" port = 993 security = "tls" username = "me@work.com" password_command = "security find-generic-password -a me@work.com -s epist -w" [accounts.smtp] host = "smtp.work.com" port = 587 security = "starttls" username = "me@work.com" password_command = "security find-generic-password -a me@work.com -s epist -w"

Password options:

You can add multiple [[accounts]] blocks for multiple IMAP/SMTP accounts.

1. Go to Google Cloud Console → create a project
2. Enable Gmail API, Google Calendar API, and People API
3. Go to "APIs & Services" → "Credentials" → "Create Credentials" → "OAuth client ID"
4. Configure OAuth consent screen:
   • User Type: External (or Internal for Workspace)
   • Add your email as a test user
   • Scopes: gmail.modify, gmail.send, calendar.events, calendar.readonly, contacts.readonly, userinfo.email, userinfo.profile
5. Create OAuth client ID — Application type: Desktop app
6. Copy the Client ID and Client Secret

Add credentials to ~/.config/epist/config.toml:

[google] clientId = "your-client-id.apps.googleusercontent.com" clientSecret = "your-client-secret"

Or use environment variables:

export EPIST_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com" export EPIST_GOOGLE_CLIENT_SECRET="your-client-secret"

Then connect:

:login 

Follow the OAuth flow in your browser. Epist supports multiple Google accounts — IMAP accounts are loaded automatically from config.toml.

Open the command palette with : and type a command:

Create or edit ~/.config/epist/config.toml:

[general] downloads_path = "~/Downloads" auto_mark_read = true auto_save_interval = 5 # seconds undo_timeout = 5 # seconds [signature] enabled = true text = """ -- Sent from Epist """ # Colors: black, red, green, yellow, blue, magenta, cyan, white, blackBright, etc. [theme] accent_color = "cyan" header_bg = "white" selected_bg = "blackBright" starred_color = "yellow" unread_style = "bold" # bold, color, or both [google] clientId = "" clientSecret = "" [keybinds] # Override defaults: action = "key" # Gmail account (uses OAuth — run :login to authenticate) [[accounts]] name = "Personal" email = "me@example.com" provider = "gmail" is_default = true # IMAP/SMTP account (any email provider) [[accounts]] name = "Work" email = "me@work.com" provider = "imap" signature = "--\nSent from my work account" [accounts.imap] host = "imap.work.com" port = 993 security = "tls" # "tls" (993), "starttls" (143), or "none" username = "me@work.com" password_command = "pass show email/work" [accounts.smtp] host = "smtp.work.com" port = 587 security = "starttls" # "tls" (465), "starttls" (587), or "none" username = "me@work.com" password_command = "pass show email/work"

Epist follows the XDG Base Directory Specification:

Configuration (~/.config/epist/): config.toml — accounts, credentials, theme, keybinds.

Data (~/.local/share/epist/):

Override with XDG_CONFIG_HOME and XDG_DATA_HOME environment variables.

Side-by-side with other terminal email clients:

^{¹ Requires external helper scripts (e.g. oauth2.py) or app-specific passwords
² Supports OAuth via external credential commands, requires manual setup}

TL;DR — Epist is built for people who want a modern, keyboard-driven terminal email experience with zero friction. Gmail users get one-command OAuth setup. IMAP/SMTP users get secure password_command integration with any secret manager. Mix both in a single client.

• Gmail sync via OAuth with PKCE
• IMAP/SMTP support (any email provider)
• Secure credentials via password_command
• Multi-account support (mix Gmail + IMAP)
• Two-column layout (list + view)
• Thread view with message navigation
• Compose, reply, reply-all, forward
• Quick inline reply
• Contact autocomplete from email history
• Dynamic Gmail labels & folders with colored dots
• IMAP folder auto-discovery (special-use flags + name heuristics)
• Collapsible Gmail categories
• Two-step search (local + remote)
• Attachment view, save, and open
• Calendar invite parsing (inline + .ics attachments)
• Calendar invite RSVP
• Bulk selection & actions
• Undo support
• Move to folder picker
• Star, archive, delete, mark read/unread
• Command palette with fuzzy matching
• Context-aware help dialog
• Local SQLite cache with instant startup
• Background sync (10s interval)
• Image navigation mode
• Link navigation with Tab
• Configurable theme & keybinds
• XDG Base Directory support
• Draft auto-save
• Homebrew distribution

• Downloadable binaries
• Offline mode improvements
• IMAP IDLE push notifications
• Email templates
• PGP/GPG encryption

MIT © 2025

_{Built with Glyph • React • a lot of ANSI escape codes}