<div align='center'> <br/> <br/> <h3>zele</h3> <p>Manage emails & calendar from your terminal. For you and your agents</p> <br/> <br/> </div>

Install

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 zele

Setup

zele login

Opens a browser for Google OAuth2. Repeat to add more accounts.

zele whoami         # show authenticated accounts
zele logout         # remove credentials

Commands

Mail

zele mail list                    # list recent threads
zele mail list --filter "is:unread"  # only unread 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)

Mail actions

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 spam <thread-id>
zele mail unspam <thread-id>
zele mail label <thread-id>
zele mail trash-spam

Search query syntax

mail 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 list --filter "is:unread"
zele mail list --filter "from:github has:attachment" --folder sent
zele mail search "from:github is:unread newer_than:7d"
zele mail watch --query "from:github has:attachment"

mail list --filter accepts the same Gmail search operators as mail search, and combines with --folder and --label.

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.

Drafts

zele draft list
zele draft create
zele draft send <draft-id>
zele draft delete <draft-id>

Labels

zele label list
zele label counts
zele label create <name>
zele label delete <label-id>

Calendar

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 availability

Shared / subscribed calendars

Zele 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" --week

Why 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.

Attachments

zele attachment list <thread-id>
zele attachment get <message-id> <attachment-id>

Profile

zele profile                      # show account info

Multi-account

All commands support --account <email> to filter by account. Without it, commands fetch from all accounts and merge results.

Output

All structured data is output as YAML. In TTY mode, keys are colored for readability. Pipe output to other tools for scripting.

License

ISC

Zele

Install / Use

README