gmail-cli

Gmail z příkazové řádky se strojově čitelným výstupem.

Kdo chce poštu z Gmailu zpracovat skriptem, má dvě možnosti a obě jsou nepohodlné. Webové rozhraní je dělané pro člověka s myší, Gmail API zase chce vlastní program, přihlášení přes OAuth, obnovování tokenů a ošetření limitů. gmail-cli tu práci dělá za něj: je to jeden spustitelný soubor gmail, který čte, hledá, třídí a odesílá poštu z terminálu a každý výsledek umí vrátit jako JSON. Hodí se pro shellové skripty, úlohy v cronu, kroky v CI i pro AI asistenta, který ovládá příkazovou řádku.

Proč příkazová řádka a ne další MCP server

Projekt vznikl jako náhrada MCP serveru pro Gmail. MCP server je dostupný jen z klienta, který MCP podporuje, kdežto příkaz v terminálu zavolá cokoli: bash, PowerShell, plánovač úloh, pipeline v CI i jazykový model s přístupem k shellu. Výstup jde rovnou do jq, do souboru nebo do dalšího programu, bez mezivrstvy.

Oproti vlastnímu skriptu nad oficiálními knihovnami Googlu odpadá psaní přihlašování a obsluhy chyb. SDK od Googlu gmail-cli nepoužívá vůbec, OAuth i volání REST API jsou napsané přímo v projektu nad fetch.

Co z toho má ten, kdo ho používá

Jeden soubor, žádné běhové prostředí

Vydání obsahuje hotové binárky pro Windows x64, macOS na Intelu i Apple Silicon a Linux x64 a ARM64. Běhové prostředí Bun je v nich zabudované, proto mají 89 až 115 MB, zato na cílovém stroji nemusí být Node.js, Python ani nic dalšího. Instalační skript stáhne správnou binárku z posledního vydání, ověří její otisk SHA-256 proti zveřejněnému souboru SHA256SUMS, uloží ji do uživatelského adresáře a přidá ho do PATH.

JSON u každého příkazu

Přepínač --json funguje u všech příkazů, takže se výstup nemusí rozebírat z textu určeného pro oči. Těla zpráv se ve výchozím stavu zkracují na 2 000 znaků, aby výpis z velké schránky nezahltil skript ani kontext jazykového modelu; --max-body-length 0 zkracování vypne.

Hromadné úpravy po tisících

Archivace, štítky, přečteno a nepřečteno nebo přesun do koše jdou přes metodu batchModify, která zpracuje až 1 000 zpráv jedním voláním API. Úklid stovek newsletterů je tak otázka jednoho příkazu, ne stovek požadavků. Trvalé smazání gmail-cli záměrně neumí: modify --trash zprávy jen přesune do koše, odkud se dají vrátit.

Odpověď zůstane ve vlákně

Příkaz reply nastaví hlavičky In-Reply-To a References, identifikátor vlákna i předmět s „Re:“, takže odpověď se u odesílatele i v odeslané poště zařadí do původní konverzace. S --all odpoví všem. Odesílací adresu vybere --from ze seznamu ověřených aliasů, který vypíše gmail aliases; bez něj odpoví z aliasu, na který původní zpráva přišla. Sdílená adresa podpory tak odpovídá svým jménem, ne hlavní adresou účtu.

Víc schránek a kalendář

Globální --account <jméno> přepne na jiný účet s vlastním tokenem, takže jeden skript obslouží osobní i pracovní schránku. Stejný nástroj pracuje s Google Kalendářem: vypíše kalendáře a nadcházející události, založí celodenní nebo časovanou událost s místem, popisem a připomínkou a událost smaže.

Výpadky a limity obslouží sám

Prošlý přístupový token se před požadavkem obnoví bez zásahu uživatele. Odpověď 429 nebo chyba 5xx se zkusí znovu, nejvýš čtyřikrát, s exponenciálně rostoucí pauzou omezenou na osm sekund. Noční úloha proto nespadne kvůli krátkému přetížení na straně Googlu.

Jak funguje přihlášení a kde leží klíče

gmail-cli nemá žádného společného OAuth klienta. Mluví s Gmailem přes Google Cloud projekt uživatele, takže přístup ke schránce zůstává pod jeho kontrolou. Průvodce gmail auth setup provede krok po kroku založením projektu, zapnutím Gmail API, nastavením souhlasové obrazovky a vytvořením klienta typu Desktop app; stažený JSON pak načte sám.

Samotné přihlášení je standardní tok pro instalované aplikace: prohlížeč se otevře na stránce Googlu a odpověď přijme dočasný server na 127.0.0.1 s náhodným portem, chráněný metodou PKCE S256. Nástroj žádá o oprávnění gmail.modify, gmail.send, calendar.events a calendar.calendarlist.readonly, tedy ne o plný přístup ke schránce. Údaje klienta a tokeny ukládá jen do %APPDATA%\gmail-cli\ na Windows, respektive do ~/.config/gmail-cli/ na macOS a Linuxu, kde soubory dostanou práva 0600. Repozitář ani CI žádné tajemství neobsahují.

Usage: gmail [options] [command]

Commands:
  auth                         Set up credentials and sign in to Google
  inbox [options]              List messages in the inbox
  search [options] <query...>  Search messages using Gmail query syntax
  read <id>                    Read a single message
  batch-read <ids...>          Read several messages in parallel
  archive <ids...>             Remove messages from the inbox
  modify [options] <ids...>    Change message state and labels
  send [options]               Compose and send a message
  reply [options] <id>         Reply to a message in its thread
  aliases                      List the "Send mail as" addresses usable with
                               --from
  labels                       List and manage labels
  drafts                       List and manage drafts
  threads <id>                 Read a full conversation thread
  attachments                  List and download message attachments
  calendar                     List calendars and manage events
  top-senders [options]        Show which senders fill your inbox

Výpis gmail --help z verze 0.3.1, zkrácený o přepínače popsané výš a dva obecné řádky.

Kde se uplatní

Ranní přehled nepřečtené pošty ve skriptu: gmail --json search is:unread vrátí pole zpráv, z něhož si jq vezme identifikátor a předmět.
Úklid schránky: výsledek hledání podle odesílatele se předá příkazu archive a stovka newsletterů zmizí z doručené pošty naráz. Kdo neví, odkud mu chodí nejvíc pošty, zeptá se top-senders.
Přílohy do složky: attachments download uloží všechny přílohy zprávy, třeba faktury, které pak zpracuje účetní skript.
Oznámení z CI: send přijme tělo zprávy ze standardního vstupu, takže krok pipeline pošle e-mail o výsledku sestavení jedním řádkem.
Podpora ze sdílené adresy: AI asistent nebo člověk připraví odpověď do souboru a reply --from ji odešle ve vlákně jménem podpory.

Stav projektu

První verze 0.1.0 vyšla v květnu 2026 s průvodcem nastavením a základními příkazy pro čtení, třídění, koncepty a přílohy. Verze 0.2.0 z června přidala příkazy pro kalendář a instalační skripty, 0.3.0 z října odpovídání ve vlákně a odesílání z aliasů. Poslední vydání je 0.3.1 z 23. října 2026, které jen aktualizovalo závislosti.

Binárky zatím nejsou podepsané, takže Windows SmartScreen při prvním spuštění hlásí neznámého vydavatele a je potřeba zvolit „Další informace“ a „Přesto spustit“. Podepisování přes program SignPath Foundation je v sestavovací pipeline připravené, ale zatím vypnuté. Testy běží v CI proti podvrženému fetch; se skutečným účtem se nástroj zkouší ručně.

Jak začít

# macOS a Linux
curl -fsSL https://raw.githubusercontent.com/nks-hub/gmail-cli/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/nks-hub/gmail-cli/main/install.ps1 | iex

gmail auth setup
gmail auth login
gmail auth status

Kdo nechce skript, stáhne binárku ručně z Releases a ověří ji proti SHA256SUMS. Ze zdrojů se sestaví přes bun run build s Bunem 1.3 a novějším.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/gmail-cli pod licencí MIT. Je napsaný v TypeScriptu, jedinou knihovnou za běhu je commander pro zpracování argumentů. V npm ani v jiném registru balíček není; jméno gmail-cli na npm patří jinému, staršímu projektu, který s tímhle nesouvisí.

← Zpět na přehled