A fast, scriptable Gmail command-line client — read, search, send, and organize Gmail from the terminal, scripts, or an AI assistant, with first-class JSON output.
Instead of clicking through the Gmail web UI — or fighting an MCP server that cannot download an attachment — drive your inbox directly:
- "List my unread inbox as JSON and pull out the subjects"
- "Search
from:linkedin.com before:2025/06/01and archive all of it" - "Download every attachment from this message"
- "Send a release notification from a CI pipeline"
- "Show me which senders fill my inbox"
It ships as a single standalone binary, so it works the same on a laptop, a server, or inside an automation.
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 interactive wizard walks you through 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.
| Feature | Description |
|---|---|
| Standalone binary | Single compiled executable for Windows, macOS, and Linux — no runtime to install |
| First-class JSON | --json on every command for reliable scripting and AI-agent use |
| Attachment support | List and download attachments — the gap most Gmail integrations leave open |
| Bulk operations | Archive, trash, label, and (un)read up to 1000 messages per API call |
| Interactive setup | A guided wizard for the Google Cloud project and OAuth client |
| Multiple accounts | Switch mailboxes with --account <name> |
| Secure by design | PKCE OAuth, credentials stored locally, never any secret in the repo |
| Resilient | Automatic token refresh and exponential backoff on rate limits |
| 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) |
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 |
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"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 only thegmail.modifyandgmail.sendscopes. Permanent deletion is intentionally unsupported —modify --trashmoves messages to Trash instead.- 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 -- --help- 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).
Contributions 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