vellem

Open Gmail in your terminal. Literally.

A keyboard-driven Gmail client that lives in your terminal. Three-panel TUI in the style of lazygit, built on the official Gmail API. Threads, replies, labels, search, archive, star, send. All without touching the mouse.

Hand-rolled ANSI on top of raw stdin. Zero React, zero ink, zero blessed. Eight runtime dependencies total. MIT-licensed.

╭─[1] Labels──────────╮ ╭─[2] Messages · page 1───────────────────╮
│ * INBOX (3)         │ │   Apr 18  GitHub      [PR] vellem: add… │
│   STARRED           │ │ ▌ Apr 18  Stripe (2)  Your invoice for… │
│   SENT              │ │   Apr 17  Linear      New comment on…   │
│   DRAFTS            │ │   …                                     │
│   IMPORTANT         │ ╰─────────────────────────────1 of 30─────╯
│   TRASH             │ ╭─[3] Preview (2)─────────────────────────╮
│   SPAM              │ │  Your invoice for April               · │
│   hello@hanoa…      │ │ ═════════════════════════════════════════│
│   Invoices          │ │  ▌ From: [email protected]             │
│   Notes             │ │  ▌ Date: Apr 18, 13:40                  │
│                     │ │  ────────────────────────────           │
│                     │ │   Hi Preet, your April invoice is ready.│
│                     │ │   …                                     │
╰─────────────1 of 11─╯ ╰─────────────────────────────────────────╯
 Enter open  a archive  d del  s star  R reply  c compose  ?  help

Quick start

npm install -g vellem
vellem auth setup    # paste in your OAuth client ID + secret
vellem auth login    # browser opens, you sign in
vellem               # opens the TUI

For other install paths (npx, from source, troubleshooting), see docs/INSTALL.md.

Setup

vellem talks to Gmail via your own Google Cloud OAuth client. You create the client; vellem just uses it. Nothing is shared.

1. Go to https://console.cloud.google.com/.
2. Create or pick a project. Enable APIs & Services → Gmail API.
3. OAuth consent screen: choose External, fill the required fields, add your own Gmail address as a test user.
4. Credentials → Create Credentials → OAuth client ID → Desktop app.
5. Either download the JSON to ~/.config/vellem/credentials.json, or run vellem auth setup and paste the Client ID + Client Secret interactively.
6. vellem auth login. A browser opens, you grant access. Tokens land in ~/.config/vellem/token.json with mode 0600.

Subsequent runs reuse the saved token silently. Run vellem auth logout to drop the token, or vellem auth reset to wipe both credentials and token.

TUI keybindings

Three panels: labels on the left (with unread counts), threads top-right, preview bottom-right. Focused panel has a green border.

Global

| Key | Action | | --- | --- | | 1 / 2 / 3 | focus labels / list / preview | | Tab | cycle panels | | / | search (Gmail query syntax) | | c | compose new message | | r | refresh current label / search now | | t | toggle background auto-refresh | | ? | help overlay | | q / Ctrl-C | quit |

List & preview

| Key | Action | | --- | --- | | j / k / ↓ / ↑ | move / scroll | | g / G | top / bottom | | Enter | open thread in preview | | Esc | list: clear search · preview: back to list | | space / b | preview: page down / up | | n / p | next / previous page of threads |

Actions (operate on the whole thread)

| Key | Action | | --- | --- | | a | archive (remove INBOX label) | | d | move to Trash | | s | toggle Star | | u | toggle Unread | | R | reply to latest sender | | A | reply-all | | o | open thread on Gmail web |

CLI commands

If you'd rather script than navigate:

vellem                                    # open the TUI
vellem list [-l INBOX] [-n 20]            # list recent messages
vellem read <id>                          # show a single message body
vellem search "<query>" [-n 20]           # Gmail search syntax
vellem send --to [email protected] --subject "hi"   # body via --body or $EDITOR
            [--body "..."] [--cc] [--bcc]
vellem labels [list|create <name>|delete <id>]
vellem auth [setup|login|logout|reset]

Background refresh

vellem polls the current label or search every 60 seconds and quietly merges new threads into the list. Selection follows the thread you had highlighted (matched by id). The status bar shows live state in the bottom-right:

• ↻ 12s (dim): time since last successful refresh
• ↻ (animated braille spinner): a refresh is in flight right now
• ↻ off: auto-refresh is paused

Press t to toggle. Auto-refresh pauses automatically while you have the editor open for compose or reply, so the list cannot shift under you mid-draft.

To change the interval:

VELLEM_REFRESH_INTERVAL=30 vellem    # poll every 30 seconds

Minimum is 10 seconds. Set to a high number if you'd rather conserve API quota.

Privacy

vellem is built so you don't have to take its word. You can verify it.

• The only outbound destination is googleapis.com.
• The only on-disk state is ~/.config/vellem/{credentials,token}.json and a temp file when you compose.
• No telemetry. No analytics. No crash reports. No update checker.
• OAuth scope is gmail.modify (read, label, send, archive, trash). Not full account access.

Full posture and audit hooks: docs/PRIVACY.md.

Performance

First inbox paint takes 3 HTTP roundtrips total: one threads.list, one batched threads.get for 30 threads, one batched labels.get for the active label. Switching labels is 2 roundtrips. Bodies are cached in RAM for the session and dropped on exit.

Contributing

PRs welcome. Please read CONTRIBUTING.md first. Anything that touches the network or filesystem boundary needs to be called out explicitly in the PR description.

For security issues, see SECURITY.md. Don't open public issues for vulnerabilities.

License

MIT. See LICENSE.