2026-03-02 15:30:09 +01:00

6.3 KiB

Raw Blame History

tuimail — User Guide

tuimail is a terminal email client. It shows your inbox in a split-pane view: the email list on top, the message preview on the bottom.

Configure tuimail

Sorry, there is no binary release for now. This setup requires that you have rust cargo installed.

Run the setup wizard:

cargo run -- --configure

(the first time --configure is active by default)

When prompted for provider choose imap/proton, choose your provider:

For Imap:

IMAP host: imap.gmail.com, port: 993, TLS: true
Username
Password
SMTP host: smtp.gmail.com, port: 465, TLS mode: smtps

Different mail providers may use other hosts and ports.

For Proton (does not require the proton-bridge)

Username: your proton account user name
Password:

Tuimail stores passwords securely in the OS keychain (macOS Keychain, GNOME Keyring, KWallet, Windows Credential Manager). No passwords are ever written to disk in plain text.

Note: every time you recreate the binary file using cargo, Macos will need reapproval (4 times) for access to the keychain.

Local cache:

Messages are safely stored locally using AES-256-GCM.

Extra Configuration needed for Gmail

1. Enable 2-Step Verification

App Passwords require 2-Step Verification to be enabled on your Google account.

Go to https://myaccount.google.com/security
Under "How you sign in to Google", click 2-Step Verification
Follow the prompts to enable it

2. Create an App Password

Go to https://myaccount.google.com/apppasswords
Enter a name (e.g. "Mail TUI") and click Create
Google will display a 16-character password — copy it

Interface

┌─────────────────────────────────────────────────────┐
│ ▶ Inbox (42 messages)                               │  ← active pane (cyan)
│   2025-01-15 10:32  Alice <alice@example.com>  Hello│
│>> 2025-01-14 09:11  Bob <bob@example.com>      Re: …│  ← selected row
│   2025-01-13 17:44  Carol <carol@example.com>  Mtg  │
├─────────────────────────────────────────────────────┤
│   Message                                           │  ← inactive pane
│                                                     │
│  Hi there,                                         │
│  Just checking in…                                 │
│                                                     │
├─────────────────────────────────────────────────────┤
│  c compose | r reply | / search | q quit | …       │  ← status bar
└─────────────────────────────────────────────────────┘

The active pane is highlighted in cyan with a ▶ prefix. Tab switches focus between the two panes.

Keyboard Reference

Key	Action
`↑` / `k`	Move up in inbox or scroll message up
`↓` / `j`	Move down in inbox or scroll message down
`Tab`	Switch focus between inbox list and message preview
`q` / `Esc`	Quit (or clear search results)

Scrolling past the last loaded message automatically fetches the next batch of 50 older emails.

Email Actions

Key	Action
`r`	Reply to the selected email
`d`	Delete the selected email (moves to Trash)
`u` / `F5`	Refresh the inbox manually

Search

Key	Action
`/`	Open the search bar
(type query)	Filter by subject or sender
`Enter`	Run the search
`Esc`	Clear search results and return to inbox

Search runs an IMAP SEARCH OR SUBJECT … FROM … query on the server so it works across your entire mailbox, not just the loaded batch.

Compose

Key	Action
`c`	Open compose window
`r`	Open compose pre-filled for replying to the selected email
`Tab`	Cycle focus: To → Subject → Body → To
`Enter`	Move to next field (To / Subject); insert newline in Body
`Ctrl+S`	Send the email
`Esc`	Cancel and discard the draft

Composing and Replying

Press c to compose a new email. The compose window opens full-screen:

┌─ ▶ Compose ──────────────────────┐
│ To:      alice@example.com       │
│ Subject: Hello                   │
├─ Body ───────────────────────────┤
│ Hi Alice,                        │
│                                  │
│ _                                │  ← cursor
└──────────────────────────────────┘
 Ctrl+S send | Esc cancel | Tab switch field

Press r to reply. The compose window opens with:

To pre-filled with the sender's address
Subject set to Re: <original subject>
Cursor placed in the Body field, ready to type
The original message shown below a separator (dimmed) — included in the sent email automatically

┌─ ▶ Compose ──────────────────────┐
│ To:      bob@example.com         │
│ Subject: Re: Weekend plans       │
├─ Body ───────────────────────────┤
│ _                                │  ← type your reply here
│ ─────────────────────────────── │
│ On 2025-01-14 09:11, Bob wrote: │
│ > Are you free Saturday?         │
└──────────────────────────────────┘

If the message body hasn't finished loading when you press r, the quote is omitted. Press Esc, wait a moment for the preview to appear, then press r again.

Auto-refresh

The inbox refreshes automatically every 30 seconds in the background. A [loading…] indicator appears in the inbox title while a refresh is in progress. Your current selection is preserved across refreshes.

6.3 KiB Raw Blame History