{"id":50853572,"url":"https://github.com/cyrus-/gmail-reader","last_synced_at":"2026-06-14T16:38:16.354Z","repository":{"id":363432752,"uuid":"1258805407","full_name":"cyrus-/gmail-reader","owner":"cyrus-","description":"Tiny read-only Gmail CLI: search messages and download attachments. Hard-pinned to the gmail.readonly scope — it cannot send, delete, or modify mail.","archived":false,"fork":false,"pushed_at":"2026-06-08T21:37:20.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T23:21:12.951Z","etag":null,"topics":["cli","gmail","oauth","python","read-only"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/cyrus-.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-06-03T23:59:40.000Z","updated_at":"2026-06-08T21:37:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cyrus-/gmail-reader","commit_stats":null,"previous_names":["cyrus-/gmail-reader"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cyrus-/gmail-reader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-%2Fgmail-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-%2Fgmail-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-%2Fgmail-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-%2Fgmail-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyrus-","download_url":"https://codeload.github.com/cyrus-/gmail-reader/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyrus-%2Fgmail-reader/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34328115,"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-14T02:00:07.365Z","response_time":62,"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":["cli","gmail","oauth","python","read-only"],"created_at":"2026-06-14T16:38:15.539Z","updated_at":"2026-06-14T16:38:16.350Z","avatar_url":"https://github.com/cyrus-.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gmail-reader\n\nA small, **read-only** Gmail CLI. The only OAuth scope it ever requests is\n`gmail.readonly`, so the credential **physically cannot send, delete, or\nmodify** mail — the Gmail API rejects any such call for this token.\n\n## Install\n\n```\ngit clone \u003cthis-repo\u003e gmail-reader\ncd gmail-reader\npython install.py            # create venv + install deps\npython install.py --link     # (optional) also put `gmail-reader` on your PATH\n```\n\nRequires Python 3.9+. Everything installs into a local `.venv` — nothing global.\n\n## One-time Google setup\n\n\u003e Google recently renamed the \"OAuth consent screen\" to the **Google Auth\n\u003e Platform**. These steps match the current (2025+) console.\n\n### 1. Create a project and enable the Gmail API\n1. Go to \u003chttps://console.cloud.google.com/\u003e and create a project (or pick one).\n2. **APIs \u0026 Services → Library →** search \"Gmail API\" → **Enable**.\n\n### 2. Configure the Google Auth Platform\n3. Open **APIs \u0026 Services → OAuth consent screen** (a.k.a. Google Auth\n   Platform). If you see *\"Google Auth Platform not configured yet\"*, click\n   **Get started** and complete the wizard:\n   - **App Information:** app name (e.g. `gmail-reader`) + a user support email.\n   - **Audience:** choose **External**. (Internal only applies to Google\n     Workspace orgs. External + test mode is free and permanent for personal\n     use — no app verification needed.)\n   - **Contact Information:** your email.\n   - **Finish:** agree to the policy and create.\n4. Still under the Google Auth Platform, open **Audience → Test users →\n   Add users** and add your own Gmail address. In test mode only listed users\n   can authorize; without this, `gmail-reader auth` is blocked.\n   - You can ignore the \"Sign in with Google\" branding and the Scopes screens —\n     the CLI requests the `gmail.readonly` scope itself at runtime.\n\n### 3. Create the OAuth client (the credentials.json)\n5. Open **Clients → Create client** (under the Google Auth Platform; older\n   consoles list this as **Credentials → Create Credentials → OAuth client ID**).\n   - Application type: **Desktop app** → Create.\n   - **Download JSON** and save it as **`credentials.json`** in this project\n     folder (next to `gmail_reader.py`).\n\n### 4. Authorize\n```\n./gmail-reader auth      # or just `gmail-reader auth` if you used --link\n```\nOpens a browser, you approve (you'll see an \"unverified app\" notice — that's\nexpected for a personal test-mode app; click through via **Advanced → Go to\ngmail-reader**), and a `token.json` is cached in this folder. Done once.\n\n## Usage\n```\ngmail-reader whoami\ngmail-reader search \"has:attachment subject:slides after:2026/01/01\"\ngmail-reader download \"has:attachment filename:pptx\" --out ./slides\n```\n`download` saves every attachment from matching messages and writes a\n`manifest.csv` (file → sender / subject / date / message id) for easy grouping.\n\n`QUERY` is standard Gmail search syntax: `from:`, `subject:`, `has:attachment`,\n`filename:pptx`, `after:YYYY/MM/DD`, `before:YYYY/MM/DD`, `label:`, etc.\n\n## Revoking access\n- Delete `token.json` to forget the cached token, and/or\n- Revoke at \u003chttps://myaccount.google.com/permissions\u003e.\n\n## Security notes\n- Scope is hard-coded to `gmail.readonly`; widening it requires editing the\n  source and re-consenting.\n- `credentials.json` and `token.json` are gitignored — they are personal\n  secrets and must never be committed.\n\n## Files\n- `gmail_reader.py` — the CLI\n- `gmail-reader` — Python launcher (resolves symlinks; uses the local `.venv`)\n- `install.py` — cross-platform installer (venv + deps, optional `--link`)\n- `gmail-reader.bat` — Windows launcher (uses the local `.venv`)\n- `requirements.txt` — Python dependencies\n- `credentials.json` / `token.json` — your secrets (gitignored)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrus-%2Fgmail-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyrus-%2Fgmail-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyrus-%2Fgmail-reader/lists"}