GitHub - longyijdos/gmail: A Gmail CLI with concise text and optional JSON output for agents and scripts. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
longyijdos
gmail
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>28 Commits<br>28 Commits
.github/workflows
.github/workflows
.husky
.husky
docs
docs
src
src
tests
tests
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
SKILL.md
SKILL.md
biome.json
biome.json
package-lock.json
package-lock.json
package.json
package.json
tsconfig.json
tsconfig.json
vitest.config.ts
vitest.config.ts
View all files
Repository files navigation
gml
Gmail, shaped for agents.
gml gives coding agents and shell workflows direct access to Gmail without a<br>daemon, browser automation, or an SDK integration. It returns compact,<br>command-specific text by default and structured JSON when exact fields matter.
Why gml
Agent-first output. Stable table headers, bounded message bodies, useful<br>summaries, and machine-readable errors.
One CLI for the full workflow. Search, read, download, send, reply,<br>forward, draft, label, archive, star, spam, and trash.
Safe automation. Query-based writes require an explicit limit or --all<br>and support --dry-run before anything changes.
Local OAuth. Credentials stay on the machine, refresh automatically, and<br>are never sent through an intermediary service.
Gmail-native. Queries use Gmail search syntax, and request exposes the<br>underlying Gmail API when a dedicated command is not enough.
Install
gml requires Node.js 22.12 or later.
npm install --global @longyijdos/gmail<br>gml --version
Start in minutes
Create a Google OAuth Desktop app client, download its JSON file, then log<br>in with read-only access:
gml auth login \<br>--client-secret-file ~/Downloads/client_secret_....json \<br>--scope readonly
Find the messages that matter and read only the one you select:
gml messages list \<br>--q 'is:unread newer_than:7d' \<br>--max-results 20 \<br>--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<br>query-based changes before applying them:
gml archive \<br>--query 'older_than:30d label:newsletters' \<br>--max-results 100 \<br>--dry-run
Designed for reliable agents
Successful results go to stdout. Errors go to stderr with a nonzero exit code.<br>Gmail commands support --json; help and authentication stay readable text.<br>Large message bodies are truncated by default, list enrichment uses bounded<br>concurrency, and retryable API failures are identified explicitly.
gml help send<br>gml auth status<br>gml profile<br>gml threads 'is:inbox newer_than:7d' --max-results 10 --summary<br>gml send --to user@example.com --subject 'Status' --body-file report.txt
Documentation
Guide<br>Use it for
Agent setup<br>Installing gml and creating Google OAuth client credentials
Agent skill<br>Install, authorize, and operate gml safely from an agent
Command reference<br>Commands, scopes, credential storage, and examples
Development<br>Local development, CI, hooks, and releases
Gmail API compatibility<br>Maintainer audit of endpoints, scopes, limits, and quotas
License
MIT
About
A Gmail CLI with concise text and optional JSON output for agents and scripts.
Resources
Readme
License
MIT license
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
stars
Watchers
watching
Forks
forks
Report repository
Releases
v0.1.1
Latest
Jul 22, 2026
+ 1 release
Packages
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
TypeScript<br>99.7%
JavaScript<br>0.3%
You can’t perform that action at this time.