Multi-account Gmail and Google Calendar client with OAuth2 auth, SQLite cache, and YAML output.
Requires bun:
# install bun (skip if already installed)
curl -fsSL https://bun.sh/install | bash # macOS/Linux
powershell -c "irm bun.sh/install.ps1|iex" # Windows
# install zele
bun install -g zelezele loginOpens a browser for Google OAuth2. Repeat to add more accounts.
zele whoami # show authenticated accounts
zele logout # remove credentialszele mail list # list recent threads
zele mail search "from:github" # 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 forward <thread-id> # forward a thread
zele mail watch # watch for new emails (poll)zele 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 label <thread-id>
zele mail trash-spammail search and mail watch --query use Gmail search operators. mail search sends the query server-side (full Gmail support), while mail watch --query evaluates a subset client-side.
| Operator | Example | Description |
|---|---|---|
from: |
from:github |
Messages from a sender |
to: |
to:me@example.com |
Messages sent to a recipient |
cc: |
cc:team@example.com |
Messages where recipient was CC'd |
subject: |
subject:invoice |
Messages with words in the subject |
is:unread |
is:unread |
Unread messages |
is:read |
is:read |
Read messages |
is:starred |
is:starred |
Starred messages |
has:attachment |
has:attachment |
Messages with attachments (heuristic in watch) |
- (negate) |
-from:noreply |
Exclude matching messages |
" " (quotes) |
"exact phrase" |
Match an exact phrase |
label: |
label:work |
Messages with a specific label (search only) |
in: |
in:sent |
Messages in a folder (search only) |
after: |
after:2024/01/01 |
Messages after a date (search only) |
before: |
before:2024/12/31 |
Messages before a date (search only) |
newer_than: |
newer_than:7d |
Messages newer than a period (search only) |
older_than: |
older_than:1m |
Messages older than a period (search only) |
filename: |
filename:pdf |
Attachment filename (search only) |
size: / larger: / smaller: |
larger:5M |
Filter by message size (search only) |
OR |
from:a OR from:b |
Match either term (search only) |
{ } |
{from:a from:b} |
Group OR terms (search only) |
Combine multiple operators to narrow results:
zele mail search "from:github is:unread newer_than:7d"
zele mail watch --query "from:github has:attachment"Operators marked (search only) are handled server-side by Gmail and only available in mail search. Using them in mail watch --query prints a warning and skips the operator.
zele 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 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.
All structured data is output as YAML. In TTY mode, keys are colored for readability. Pipe output to other tools for scripting.
ISC