{"id":50917787,"url":"https://github.com/nks-hub/gmail-cli","last_synced_at":"2026-06-16T17:02:25.669Z","repository":{"id":359646047,"uuid":"1246963504","full_name":"nks-hub/gmail-cli","owner":"nks-hub","description":"A fast, scriptable Gmail command-line client with first-class JSON output.","archived":false,"fork":false,"pushed_at":"2026-05-22T20:13:21.000Z","size":62,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T21:59:39.713Z","etag":null,"topics":["bun","cli","command-line","email","gmail","gmail-api","oauth2","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nks-hub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T18:47:16.000Z","updated_at":"2026-05-22T20:13:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nks-hub/gmail-cli","commit_stats":null,"previous_names":["nks-hub/gmail-cli"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nks-hub/gmail-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nks-hub%2Fgmail-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nks-hub%2Fgmail-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nks-hub%2Fgmail-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nks-hub%2Fgmail-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nks-hub","download_url":"https://codeload.github.com/nks-hub/gmail-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nks-hub%2Fgmail-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34415248,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","cli","command-line","email","gmail","gmail-api","oauth2","typescript"],"created_at":"2026-06-16T17:02:24.595Z","updated_at":"2026-06-16T17:02:25.664Z","avatar_url":"https://github.com/nks-hub.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gmail-cli\n\n[![CI](https://github.com/nks-hub/gmail-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/nks-hub/gmail-cli/actions)\n[![Release](https://img.shields.io/github/v/release/nks-hub/gmail-cli.svg)](https://github.com/nks-hub/gmail-cli/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-3178c6.svg)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-1.3+-f9f1e1.svg)](https://bun.sh/)\n\n\u003e 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.\n\n---\n\n## Why?\n\nInstead of clicking through the Gmail web UI — or fighting an MCP server that\ncannot download an attachment — drive your inbox directly:\n\n- \"List my unread inbox as JSON and pull out the subjects\"\n- \"Search `from:linkedin.com before:2025/06/01` and archive all of it\"\n- \"Download every attachment from this message\"\n- \"Send a release notification from a CI pipeline\"\n- \"Show me which senders fill my inbox\"\n\nIt ships as a single standalone binary, so it works the same on a laptop, a\nserver, or inside an automation.\n\n---\n\n## Quick Start\n\n### Installation\n\n#### Install script\n\n**macOS / Linux:**\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/nks-hub/gmail-cli/main/install.sh | sh\n```\n\n**Windows (PowerShell):**\n\n```powershell\nirm https://raw.githubusercontent.com/nks-hub/gmail-cli/main/install.ps1 | iex\n```\n\nThe script downloads the correct binary for your platform from the latest\nrelease, verifies its SHA-256 checksum, installs it to a per-user directory,\nand adds that directory to your `PATH`. Override the location with the\n`GMAIL_CLI_INSTALL_DIR` environment variable, then restart your terminal.\n\n#### Download manually\n\nGrab the binary for your platform from the\n[Releases](https://github.com/nks-hub/gmail-cli/releases) page, rename it to\n`gmail` (`gmail.exe` on Windows), put it on your `PATH`, and — on macOS or\nLinux — mark it executable with `chmod +x gmail`. Verify it against the\npublished `SHA256SUMS` file.\n\n\u003e Release binaries are not yet code-signed, so Windows SmartScreen may warn\n\u003e about an unknown publisher on first run. Choose **More info → Run anyway**.\n\n#### From source\n\nRequires [Bun](https://bun.sh) 1.3 or newer.\n\n```sh\ngit clone https://github.com/nks-hub/gmail-cli.git\ncd gmail-cli\nbun install \u0026\u0026 bun run build\n```\n\n### Authentication\n\n`gmail-cli` talks to Gmail through your own Google Cloud project, so mailbox\naccess stays under your control. The interactive wizard walks you through it:\n\n```sh\ngmail auth setup     # create the Google Cloud project and OAuth client\ngmail auth login     # sign in through the browser\ngmail auth status    # confirm you are signed in\n```\n\n### Usage\n\n```sh\ngmail inbox\ngmail --json search is:unread | jq '.[].subject'\n```\n\nGlobal options (`--json`, `--account`, `--max-body-length`) must be given\nbefore the command, e.g. `gmail --json inbox`.\n\n---\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Standalone binary** | Single compiled executable for Windows, macOS, and Linux — no runtime to install |\n| **First-class JSON** | `--json` on every command for reliable scripting and AI-agent use |\n| **Attachment support** | List and download attachments — the gap most Gmail integrations leave open |\n| **Bulk operations** | Archive, trash, label, and (un)read up to 1000 messages per API call |\n| **Interactive setup** | A guided wizard for the Google Cloud project and OAuth client |\n| **Multiple accounts** | Switch mailboxes with `--account \u003cname\u003e` |\n| **Secure by design** | PKCE OAuth, credentials stored locally, never any secret in the repo |\n| **Resilient** | Automatic token refresh and exponential backoff on rate limits |\n\n---\n\n## Commands\n\n### Authentication\n| Command | Description |\n|---------|-------------|\n| `auth setup` | Interactive Google OAuth setup wizard |\n| `auth login` / `logout` / `status` | Sign in via the browser, sign out, show status |\n\n### Reading\n| Command | Description |\n|---------|-------------|\n| `inbox` | List messages in the inbox |\n| `search \u003cquery\u003e` | Search with Gmail query syntax |\n| `read \u003cid\u003e` | Read a single message |\n| `batch-read \u003cids...\u003e` | Read several messages in parallel |\n| `threads \u003cid\u003e` | Read a full conversation thread |\n\n### Organizing\n| Command | Description |\n|---------|-------------|\n| `archive \u003cids...\u003e` | Remove messages from the inbox |\n| `modify \u003cids...\u003e` | `--read/--unread/--star/--trash/--spam/--add-label/--remove-label` |\n| `labels list\\|create\\|rename\\|delete` | Manage labels |\n\n### Composing\n| Command | Description |\n|---------|-------------|\n| `send` | Compose and send a message (flags, file, or stdin) |\n| `drafts list\\|create\\|send\\|delete` | Manage drafts |\n\n### Attachments \u0026 analysis\n| Command | Description |\n|---------|-------------|\n| `attachments list\\|download` | List and download message attachments |\n| `top-senders` | Show which senders fill your inbox |\n\n### Calendar\n\n| Command | Description |\n|---------|-------------|\n| `calendar list` | List the calendars in the account |\n| `calendar events` | List upcoming events (`--calendar`, `--from`, `--to`, `--query`, `--max`) |\n| `calendar add \u003csummary\u003e` | Create an event (`--date` for all-day, `--start`/`--end` for timed, `--description`, `--location`, `--reminder \u003cmin\u003e`) |\n| `calendar delete \u003ceventId\u003e` | Delete an event |\n\n---\n\n## Common Workflows\n\n### 1. Triage unread mail from a script\n\n```sh\ngmail --json search is:unread | jq -r '.[] | \"\\(.id)\\t\\(.subject)\"'\n```\n\n### 2. Bulk-archive newsletters\n\n```sh\ngmail --json search from:newsletter@example.com -n 100 \\\n  | jq -r '.[].id' | xargs gmail archive\n```\n\n### 3. Save all attachments from a message\n\n```sh\ngmail attachments download \u003cmessageId\u003e --out ./downloads\n```\n\n### 4. Send a notification from CI\n\n```sh\necho \"Build succeeded.\" | gmail send --to team@example.com --subject \"CI\"\n```\n\n---\n\n## Output\n\nEvery command prints human-readable text by default and structured JSON when\n`--json` is set. `--max-body-length \u003cn\u003e` truncates message bodies (`0` =\nunlimited).\n\n---\n\n## Security\n\n- OAuth credentials and tokens are stored only on your machine, under\n  `%APPDATA%\\gmail-cli\\` (Windows) or `~/.config/gmail-cli/` (macOS/Linux).\n- `gmail-cli` requests only the `gmail.modify` and `gmail.send` scopes.\n  Permanent deletion is intentionally unsupported — `modify --trash` moves\n  messages to Trash instead.\n- The repository and CI never contain any secret.\n\nSee [SECURITY.md](SECURITY.md) for how to report vulnerabilities.\n\n---\n\n## Development\n\n```sh\nbun install        # install dependencies\nbun test           # run the test suite\nbun run typecheck  # type-check with tsc\nbun run build      # compile the binary to dist/gmail\nbun run start -- --help\n```\n\n---\n\n## Requirements\n\n- **To run:** nothing — the release binary is self-contained.\n- **To build from source:** [Bun](https://bun.sh) 1.3 or newer.\n- **A Google account** and a Google Cloud project (the `auth setup` wizard\n  creates the OAuth client for you).\n\n---\n\n## Contributing\n\nContributions are welcome! For larger changes, open an issue first.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: description'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## Support\n\n- 📧 **Email:** dev@nks-hub.cz\n- 🐛 **Bug reports:** [GitHub Issues](https://github.com/nks-hub/gmail-cli/issues)\n- 📖 **Gmail API:** [developers.google.com/gmail/api](https://developers.google.com/gmail/api)\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n## Links\n\n- [Gmail API](https://developers.google.com/gmail/api)\n- [Bun](https://bun.sh/)\n- [NKS Hub](https://github.com/nks-hub)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by \u003ca href=\"https://github.com/nks-hub\"\u003eNKS Hub\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnks-hub%2Fgmail-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnks-hub%2Fgmail-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnks-hub%2Fgmail-cli/lists"}