Docs: https://lubabs770.github.io/parcel/
parcel
A light, fast, yummy terminal mail client for any email CLI.
- Drives any email CLI — himalaya ships built in, point it at another with a few command templates
- Starts instantly, no daemon, no index
- Live Omarchy theme: follows your system theme, repaints on change
- 8 built-in themes (and your own)
- Optimistic triage: star, archive, move, delete update the screen immediately, the backend call happens after
- Compose, reply, and forward hand off to
$EDITOR
- Reading and triage are also commands, with
--json for scripts. Compose, reply and forward live in the TUI, or parcel send a draft you wrote
Install
curl -fsSL https://raw.githubusercontent.com/lubabs770/parcel/main/install.sh | sh
Downloads the right binary for your OS/arch, verifies its sha256 against the
release's checksums, test-runs it, then installs to ~/.local/bin (atomically —
a running parcel is never half-overwritten).
BIN_DIR=/some/dir ... | sh to install somewhere elseVERSION=v0.1.0 ... | sh to pin a release instead of latest
parcel needs an email CLI to drive. The default backend is
himalaya; install and configure that
(or another CLI — see Config below) first.
The TUI
| Key | Action |
|---|
j / k | down / up |
g / G | top / bottom |
enter | open |
esc | back |
tab | next pane |
/ | search |
r / R | reply / reply all |
f | forward |
c | compose |
s | star |
u | toggle read |
d | delete |
m | move to… |
a | archive |
ctrl+p | command palette |
t | themes |
? | help |
q | quit |
Arrow keys, Home and End always move, and Ctrl+C always quits, regardless of
overrides. Mouse works
too: scroll a pane, click to select, double-click to open.
Every key is rebindable — see Config below.
Config
~/.config/parcel/
├── config.toml # backend, theme, page_size, inbox, archive
├── keys.toml # key overrides
└── backends/
└── himalaya.toml # command templates for the himalaya backend
parcel config init writes the defaults above for editing (never overwrites
an existing file). backends/himalaya.toml is written fully commented out:
uncomment only the lines you want to override, so the rest keeps following the
built-in preset. parcel config path prints the config directory.
The himalaya preset is built in — no file needed until you want to change it.
Every key in config.toml is optional; the defaults are backend = "himalaya",
theme = "auto", page_size = 50, inbox = "inbox", archive = "Archive".
To drive another CLI, set backend and write backends/<name>.toml: a command
template per action, with {mailbox} {id} {page} {size} {query} {flag} {target} filled in (and {name...} to split a value on whitespace), plus a
[fields] table mapping its JSON output to parcel's envelope shape:
# ~/.config/parcel/config.toml
backend = "mycli"
# ~/.config/parcel/backends/mycli.toml
mailboxes = "mycli folders --json"
list = "mycli ls --folder {mailbox} --page {page} --json"
read = "mycli show {id}"
[fields]
items = "" # output is a bare array
id = "uid"
subject = "subject"
from = "sender"
date = "date"
flags = "flags"
mailbox_items = ""
mailbox_name = "name"
Leave an action's template out to disable its key.
Omarchy
With theme = "auto" (the default), parcel follows the active
Omarchy theme and re-derives any color layer Omarchy's
palette doesn't define.
parcel omarchy hook install adds a line to Omarchy's theme-set hook that
signals running parcels to repaint instantly on a theme change. Without it,
parcel still notices within about a second via polling — the hook just makes
it immediate. parcel omarchy hook uninstall removes the line.
CLI
parcel open the TUI
parcel mailboxes list mailboxes
parcel list [-m MBOX] [-p N] list envelopes in a mailbox
parcel search QUERY search a mailbox
parcel read ID print a message
parcel flag ID [--flag F] set a flag (seen|flagged, default flagged)
parcel unflag ID [--flag F] clear a flag
parcel move ID TARGET move a message to another mailbox
parcel delete ID delete a message
parcel send [FILE] send a raw RFC 5322 message (FILE or stdin)
parcel config init|path write/print the config files
parcel omarchy hook install|uninstall repaint running parcels on theme change
parcel doctor check the backend, templates and theme setup
parcel log [-n LINES] show the end of the error log
parcel upgrade [--check] install the latest release (or just check)
Add --json to any data-producing command for machine-readable output.
Commands that act on a mailbox accept -m MAILBOX (default: your inbox).
parcel doctor checks that every configured backend command is on $PATH,
that mailboxes actually load, and whether the Omarchy hook is installed.
parcel log shows the end of parcel's error log — every failed backend call
is recorded there with its command and stderr, even when the TUI only shows a
short status-bar message.
Troubleshooting
himalaya can't reach the macOS keychain. This happens when parcel is
launched from a session without keychain access — a detached tmux or a
headless/SSH session, for example. The backend error shows up in the status
bar; run parcel log for the full command and stderr.
