# Show HN: Gml – A Gmail CLI designed for agents

> Source: <https://github.com/longyijdos/gmail>
> Published: 2026-07-22 09:28:46+00:00

**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, and`request`

exposes the underlying Gmail API when a dedicated command is not enough.

`gml`

requires [Node.js](https://nodejs.org/) 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 credentials[Agent skill](/longyijdos/gmail/blob/main/SKILL.md)`gml`

safely from an agent