Gmail and Google Calendar command-line client: read, search, send and organize mail from the terminal, scripts or an AI assistant, with JSON output on every command.
- 📦 Standalone binary - one compiled executable for Windows, macOS and Linux, no runtime to install
- 🧾 JSON output -
--jsonon every command - 📎 Attachments - list and download message attachments
- ⚡ Bulk operations - archive, trash, label, and (un)read up to 1000 messages per API call
- 🧙 Interactive setup - a wizard for the Google Cloud project and OAuth client
- 👥 Multiple accounts - switch mailboxes with
--account <name> - 🔒 Local credentials - PKCE OAuth, tokens stored on your machine, no secret in the repo
- 🔁 Retries - automatic token refresh and exponential backoff on rate limits
- To run: nothing, the release binary is self-contained.
- To build from source: Bun 1.3 or newer.
- A Google account and a Google Cloud project (the
auth setupwizard creates the OAuth client for you).
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/nks-hub/gmail-cli/main/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/nks-hub/gmail-cli/main/install.ps1 | iexThe script downloads the correct binary for your platform from the latest
release, verifies its SHA-256 checksum, installs it to a per-user directory,
and adds that directory to your PATH. Override the location with the
GMAIL_CLI_INSTALL_DIR environment variable, then restart your terminal.
Grab the binary for your platform from the
Releases page, rename it to
gmail (gmail.exe on Windows), put it on your PATH, and on macOS or
Linux mark it executable with chmod +x gmail. Verify it against the
published SHA256SUMS file.
Release binaries are not yet code-signed, so Windows SmartScreen may warn about an unknown publisher on first run. Choose More info → Run anyway.
Requires Bun 1.3 or newer.
git clone https://github.com/nks-hub/gmail-cli.git
cd gmail-cli
bun install && bun run buildgmail-cli talks to Gmail through your own Google Cloud project, so mailbox
access stays under your control. The wizard creates it:
gmail auth setup # create the Google Cloud project and OAuth client
gmail auth login # sign in through the browser
gmail auth status # confirm you are signed ingmail inbox
gmail --json search is:unread | jq '.[].subject'Global options (--json, --account, --max-body-length) must be given
before the command, e.g. gmail --json inbox.
| Command | Description |
|---|---|
auth setup |
Interactive Google OAuth setup wizard |
auth login / logout / status |
Sign in via the browser, sign out, show status |
| Command | Description |
|---|---|
inbox |
List messages in the inbox |
search <query> |
Search with Gmail query syntax |
read <id> |
Read a single message |
batch-read <ids...> |
Read several messages in parallel |
threads <id> |
Read a full conversation thread |
| Command | Description |
|---|---|
archive <ids...> |
Remove messages from the inbox |
modify <ids...> |
--read/--unread/--star/--trash/--spam/--add-label/--remove-label |
labels list|create|rename|delete |
Manage labels |
| Command | Description |
|---|---|
send |
Compose and send a message (flags, file, or stdin); --from picks the sender |
reply <id> |
Reply inside the original thread (--all, --from, --cc, --reply-to) |
aliases |
List the "Send mail as" addresses accepted by --from |
drafts list|create|send|delete |
Manage drafts |
| Command | Description |
|---|---|
attachments list|download |
List and download message attachments |
top-senders |
Show which senders fill your inbox |
| Command | Description |
|---|---|
calendar list |
List the calendars in the account |
calendar events |
List upcoming events (--calendar, --from, --to, --query, --max) |
calendar add <summary> |
Create an event (--date for all-day, --start/--end for timed, --description, --location, --reminder <min>) |
calendar delete <eventId> |
Delete an event |
gmail --json search is:unread | jq -r '.[] | "\(.id)\t\(.subject)"'gmail --json search from:newsletter@example.com -n 100 \
| jq -r '.[].id' | xargs gmail archivegmail attachments download <messageId> --out ./downloadsecho "Build succeeded." | gmail send --to team@example.com --subject "CI"gmail reply <messageId> --from support@example.com --body-file answer.txtreply sets In-Reply-To, References and the thread id, so the answer lands in the same conversation for both sides. Without --from it sends from the alias the original message was addressed to, falling back to the account default. --from accepts only verified addresses listed by gmail aliases, because Gmail would otherwise replace the sender with the primary address.
Every command prints human-readable text by default and structured JSON when
--json is set. --max-body-length <n> truncates message bodies (0 =
unlimited).
- OAuth credentials and tokens are stored only on your machine, under
%APPDATA%\gmail-cli\(Windows) or~/.config/gmail-cli/(macOS/Linux). gmail-clirequests thegmail.modify,gmail.send,calendar.eventsandcalendar.calendarlist.readonlyscopes. Permanent deletion of mail is not supported;modify --trashmoves messages to Trash.- The repository and CI never contain any secret.
See SECURITY.md for how to report vulnerabilities.
bun install # install dependencies
bun test # run the test suite
bun run typecheck # type-check with tsc
bun run build # compile the binary to dist/gmail
bun run start -- --helpContributions are welcome! For larger changes, open an issue first.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: description') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
See CONTRIBUTING.md for details.
- 📧 Email: dev@nks-hub.cz
- 🐛 Bug reports: GitHub Issues
- 📖 Gmail API: developers.google.com/gmail/api
MIT License — see LICENSE for details.
Made with ❤️ by NKS Hub