sander/tuimail
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tuimail/USAGE.md
Shautvast facb44d561 Store credentials in OS keychain via keyring crate 
Passwords are no longer stored in config.toml. Instead:
- New setup wizard (--configure) prompts for credentials on first run
  and stores them in the OS keychain (macOS Keychain, GNOME Keyring /
  KWallet on Linux, Windows Credential Manager)
- Env-var fallback: TUIMAIL_<KEY> for headless environments
- ProtonMail session token moves from session.json to the keychain
- Config file path moves to {config_dir}/tuimail/config.toml

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-25 10:50:23 +01:00

249 lines
8.3 KiB
Markdown
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.
---
## Setup
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.
### First-time setup
Simply run tuimail — if no config file exists it launches an interactive
wizard automatically:
```bash
cargo run
```
The wizard prompts for your provider, server settings, and passwords, then
saves the config file and stores all passwords in the OS keychain.
### Re-configure / update credentials
```bash
cargo run -- --configure
```
All prompts show current values in brackets. Press Enter to keep a value, or
type a new one. Password prompts show `[stored]` when a value already exists
in the keychain.
### Headless / CI environments (env-var fallback)
If the OS keychain is unavailable, export the passwords as environment
variables:
| Variable | Credential |
|----------|------------|
| `TUIMAIL_IMAP_PASSWORD` | IMAP password |
| `TUIMAIL_SMTP_PASSWORD` | SMTP password |
| `TUIMAIL_PROTON_PASSWORD` | ProtonMail login password |
| `TUIMAIL_PROTON_MAILBOX_PASSWORD` | ProtonMail mailbox password (two-password mode) |
Example:
```bash
TUIMAIL_IMAP_PASSWORD=hunter2 cargo run
```
**Common provider settings**
| Provider | IMAP host | IMAP port | use_tls | SMTP host | SMTP port | tls_mode |
|----------|-----------|-----------|---------|-----------|-----------|----------|
| Gmail | imap.gmail.com | 993 | true | smtp.gmail.com | 465 | smtps |
| Outlook/Hotmail | outlook.office365.com | 993 | true | smtp.office365.com | 587 | starttls |
| ProtonMail | see ProtonMail section below ||||| |
| Local test server | localhost | 143 | false | localhost | 25 | none |
> **Gmail note:** You must use an [App Password](https://myaccount.google.com/apppasswords),
> not your regular password. Enable 2-Step Verification first, then generate an
> App Password for "Mail".
### ProtonMail
tuimail can talk to ProtonMail directly — no separate bridge process needed.
The bridge starts automatically in-process when `provider = "proton"` is set.
**1. Build with ProtonMail support:**
```bash
cargo build --features proton
```
**2. Run the setup wizard:**
```bash
cargo run --features proton -- --configure
```
The wizard prompts for your ProtonMail username and password (stored in
keychain), two-password mode, and bridge ports. The bridge local password is
auto-generated and stored in the keychain.
**3. Run:**
```bash
cargo run --features proton
```
The bridge authenticates with ProtonMail before the TUI opens. Messages are
decrypted on the fly; sent mail is encrypted end-to-end automatically.
Then run (standard providers):
```bash
cargo run --release
```
---
## 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
### Navigation
| 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.
---
## Configuration Reference
### `[imap]`
| Key | Type | Description |
|-----|------|-------------|
| `host` | string | IMAP server hostname |
| `port` | integer | IMAP port (usually 993 with TLS, 143 without) |
| `username` | string | Login username (usually your full email address) |
| `use_tls` | bool | `true` for IMAPS (port 993), `false` for plain/STARTTLS |
> Password is stored in the OS keychain. Use `--configure` to set or update it.
### `[smtp]`
| Key | Type | Description |
|-----|------|-------------|
| `host` | string | SMTP server hostname |
| `port` | integer | SMTP port |
| `username` | string | Login username |
| `tls_mode` | string | `none`, `starttls`, or `smtps` |
| `from` | string | Sender address shown to recipients, e.g. `Name <addr>` |
> Password is stored in the OS keychain. Use `--configure` to set or update it.
Reference in a new issue View git blame Copy permalink