Multi-account email and calendar client supporting Google OAuth and IMAP/SMTP (Fastmail, Outlook, any provider). SQLite cache, YAML output.
All CLI commands work with Node.js (v18+). The interactive TUI (zele with no subcommand) requires Bun and will auto-spawn it if available.
# with npm / npx (CLI commands only, no TUI)
npm install -g zele
# with bun (full support including TUI)
bun install -g zeleIf you install via npm and run
zele(the TUI), it will try to findbunin your PATH and re-spawn automatically. If bun is not installed, you'll get install instructions.
zele loginOpens a browser for Google OAuth2. Repeat to add more accounts.
zele login is interactive — it prints an authorization URL and waits for the redirect URL to be pasted back. In agent or headless environments, run it inside a tmux session so the process persists and can be driven programmatically:
# start login in a tmux session
tmux new-session -d -s zele-login 'zele login'
# read the authorization URL from tmux output
tmux capture-pane -t zele-login -p
# after the user completes consent in their browser, paste the redirect URL
tmux send-keys -t zele-login 'http://localhost:...?code=...' Enter
# verify login succeeded
tmux capture-pane -t zele-login -p
tmux kill-session -t zele-loginIMAP/SMTP login is non-interactive and requires no tmux wrapper.
For non-Google providers (Fastmail, Outlook, Gmail with app passwords, any IMAP server):
# Fastmail
zele login imap \
--email you@fastmail.com \
--imap-host imap.fastmail.com --imap-port 993 \
--smtp-host smtp.fastmail.com --smtp-port 465 \
--password "your-app-password"
# Gmail (app password)
zele login imap \
--email you@gmail.com \
--imap-host imap.gmail.com --imap-port 993 \
--smtp-host smtp.gmail.com --smtp-port 465 \
--password "your-app-password"
# Outlook
zele login imap \
--email you@outlook.com \
--imap-host outlook.office365.com --imap-port 993 \
--smtp-host smtp-mail.outlook.com --smtp-port 587 \
--password "your-password"
# IMAP-only (no sending)
zele login imap \
--email reader@example.com \
--imap-host imap.example.com --imap-port 993 \
--password "pass"Use --imap-user / --smtp-user if the login username differs from your email. Omit --smtp-host for read-only access.
zele whoami # show authenticated accounts (type, capabilities)
zele logout # remove credentialszele mail list --limit 100 # list up to 100 recent threads
zele mail list --filter "is:unread" --limit 100 # list unread threads
zele mail list --filter "is:unread" --limit 100 | yq '.[].id' | xargs zele mail read # read all unread
zele mail search "from:github" --limit 100 # search with Gmail query syntax
zele mail read <thread-id> # read a thread
zele mail send # send an email
zele mail reply <thread-id> # reply to a thread
zele mail reply <thread-id> --attach report.xlsx # reply with an attachment
zele mail forward <thread-id> # forward a thread
zele mail watch # wait for the next new email
zele mail watch --filter "is:unread from:alice" # wait for a specific email
zele mail watch --timeout 300 # wait up to 5 minutesmail watch blocks until the first email matching the filter arrives, prints it, and exits (code 0). If --timeout is set and no match arrives in time, it exits with code 1. This is useful for agents that need to send an email and then wait for the reply:
zele mail send --to bob@example.com --subject "Question" --body "Hey, can you check this?"
zele mail watch --filter "is:unread from:bob subject:Re:Question" --timeout 600zele mail star <thread-id>
zele mail unstar <thread-id>
zele mail archive <thread-id>
zele mail trash <thread-id>
zele mail untrash <thread-id>
zele mail read-mark <thread-id>
zele mail unread-mark <thread-id>
zele mail spam <thread-id>
zele mail unspam <thread-id>
zele mail label <thread-id>
zele mail trash-spamAll action commands accept one or more thread IDs and an optional --account flag. On Google accounts, archiving removes the INBOX label. On IMAP accounts, it moves the message to the server's Archive folder (Archive, Archives, All Mail, [Gmail]/All Mail, or INBOX.Archive).
# archive a single thread
zele mail archive 18f3b7c9d2a1e4f0
# archive multiple threads at once
zele mail archive 18f3b7c9d2a1e4f0 18f3b7c9d2a1e4f1 18f3b7c9d2a1e4f2
# archive from a specific account when you have multiple
zele mail archive 18f3b7c9d2a1e4f0 --account you@example.com
# bulk archive: pipe thread IDs from a search
zele mail search "from:noreply@github.com older_than:7d" --limit 100 \
| yq '.[].id' \
| xargs zele mail archive
# list archived threads later
zele mail list --filter "in:archive" --limit 100For Google accounts, mail search and mail list --filter use Gmail search operators server-side. For IMAP accounts, queries are translated to IMAP SEARCH criteria (a subset is supported).
| Operator | Example | IMAP | |
|---|---|---|---|
from: |
from:github |
yes | yes |
to: |
to:me@example.com |
yes | yes |
subject: |
subject:invoice |
yes | yes |
is:unread |
is:unread |
yes | yes |
is:starred |
is:starred |
yes | yes |
has:attachment |
has:attachment |
yes | yes |
newer_than: |
newer_than:7d |
yes | yes |
older_than: |
older_than:1m |
yes | yes |
after: |
after:2024/01/01 |
yes | yes |
before: |
before:2024/12/31 |
yes | yes |
cc: |
cc:team@example.com |
yes | no |
- (negate) |
-from:noreply |
yes | no |
" " (quotes) |
"exact phrase" |
yes | no |
label: |
label:work |
yes | no |
in: |
in:sent |
yes | no |
filename: |
filename:pdf |
yes | no |
size: / larger: / smaller: |
larger:5M |
yes | no |
OR / { } |
from:a OR from:b |
yes | no |
zele mail list --filter "is:unread" --limit 100
zele mail list --filter "from:github newer_than:7d" --folder sent --limit 100
zele mail search "from:github is:unread newer_than:7d" --limit 100
zele mail watch --filter "from:github has:attachment" --timeout 300zele draft list
zele draft create
zele draft send <draft-id>
zele draft delete <draft-id>zele label list
zele label counts
zele label create <name>
zele label delete <label-id>zele mail filter listzele cal list # list calendars
zele cal events # upcoming events
zele cal get <event-id> # event details
zele cal create # create an event
zele cal update <event-id> # update an event
zele cal delete <event-id> # delete an event
zele cal respond <event-id> # accept/decline
zele cal freebusy # check availabilityZele uses Google CalDAV for calendar access. By default, Google only syncs calendars you own over CalDAV — shared or subscribed calendars (e.g. a partner's calendar) won't appear in zele cal list even after accepting the share invitation.
To fix this, visit Google's CalDAV sync settings and enable the shared calendar:
- Open https://www.google.com/calendar/syncselect (logged in as the account you use with zele)
- Check the box next to any shared calendar you want to access
- Click Save
After that, zele cal list will show the shared calendar and you can query it:
zele cal events --calendar "other-person@gmail.com" --weekWhy is this needed? Google's CalDAV endpoint only exposes calendars marked for sync (originally designed for mobile device sync). The Google Calendar web UI uses a different internal API, so calendars visible there may not appear via CalDAV until explicitly enabled at the sync settings page.
zele attachment list <thread-id>
zele attachment get <message-id> <attachment-id>zele profile # show account infoAll commands support --account <email> to filter by account. Without it, commands fetch from all accounts and merge results.
Google and IMAP/SMTP accounts work side by side — mail list merges results from both. Google-only features (labels, filters, calendar) show a helpful error when used with IMAP accounts.
| Feature | IMAP/SMTP | |
|---|---|---|
| List, read, search emails | yes | yes |
| Send, reply, forward | yes | yes (requires SMTP) |
| Star, archive, trash, mark read | yes | yes |
| Drafts | yes | yes |
| Attachments | yes | yes |
| Watch for new emails | yes | yes |
| Date/sender/subject filters | yes | yes |
| Labels | yes | no (IMAP uses folders) |
| Filters | yes | no |
| Calendar | yes | no |
| Gmail search operators | full | subset (see table above) |
All structured data is output as YAML. In TTY mode, keys are colored for readability. Pipe output to other tools for scripting.
Always run zele --help first. The top-level help already contains every subcommand, option, and flag — there is no need to run zele <command> --help separately. The help output is the source of truth. Read it in full — never pipe through head, tail, or sed to truncate.
Never use the TUI. Running zele with no subcommand launches a human-facing terminal UI for browsing email. Agents must use the CLI subcommands (zele mail list, zele cal events, etc.) which output structured YAML that can be parsed and piped.
Always run zele whoami before account-scoped commands. When the user asks to check email "for a specific account" (e.g. "my work email", "my personal Gmail"), run zele whoami first to list connected accounts and find the exact address to pass to --account. Never guess the email — pick it from the whoami output. The output also shows account type (google or imap_smtp) and capabilities so you know which features are available.
# list connected accounts first
zele whoami
# then scope commands to the right account
zele mail list --account user@work.comPrefer YAML parsing over regex. Pipe command output through yq to extract IDs and fields reliably:
# read all unread emails
zele mail list --filter "is:unread" --limit 100 | yq '.[].id' | xargs zele mail read
# bulk archive unread
zele mail list --filter "is:unread" --limit 100 | yq '.[].id' | xargs zele mail archiveISC
