Gmail, shaped for agents.
gml
gives coding agents and shell workflows direct access to Gmail without a daemon, browser automation, or an SDK integration. It returns compact, command-specific text by default and structured JSON when exact fields matter.
Agent-first output. Stable table headers, bounded message bodies, useful summaries, and machine-readable errors.One CLI for the full workflow. Search, read, download, send, reply, forward, draft, label, archive, star, spam, and trash.Safe automation. Query-based writes require an explicit limit or--all
and support--dry-run
before anything changes.Local OAuth. Credentials stay on the machine, refresh automatically, and are never sent through an intermediary service.Gmail-native. Queries use Gmail search syntax, andrequest
exposes the underlying Gmail API when a dedicated command is not enough.
gml
requires Node.js 22.12 or later.
npm install --global @longyijdos/gmail
gml --version
Create a Google OAuth Desktop app client, download its JSON file, then log in with read-only access:
gml auth login \
--client-secret-file ~/Downloads/client_secret_....json \
--scope readonly
Find the messages that matter and read only the one you select:
gml messages list \
--q 'is:unread newer_than:7d' \
--max-results 20 \
--summary
gml read MESSAGE_ID
Use JSON when another tool needs stable field access:
gml messages list --q 'from:alerts@example.com' --max-results 10 --json
Need to organize or send mail? Reauthorize with --scope modify
, then preview query-based changes before applying them:
gml archive \
--query 'older_than:30d label:newsletters' \
--max-results 100 \
--dry-run
Successful results go to stdout. Errors go to stderr with a nonzero exit code.
Gmail commands support --json
; help and authentication stay readable text. Large message bodies are truncated by default, list enrichment uses bounded concurrency, and retryable API failures are identified explicitly.
gml help send
gml auth status
gml profile
gml threads 'is:inbox newer_than:7d' --max-results 10 --summary
gml send --to user@example.com --subject 'Status' --body-file report.txt
| Guide | Use it for |
|---|---|
gml
and creating Google OAuth client credentialsAgent skillgml
safely from an agent