📧 v1.0.0 Stable • Native Rust 2024 • Gmail API v1 • Release Notes →

A Lightning Fast CLI for Gmail

Search messages, hydrate threads, download attachments, and prepare drafts safely from your terminal or AI workflows.

$cargo install --git https://github.com/SpaceCorps/Gmail-Cli --locked

Core Advantages

⚡

1–3 ms Startup

A single static Rust 2024 binary with zero runtime dependencies. Instant startup for shell pipelines and scripts.

🛡️

Draft Safety Guarantee

The CLI can only create, update, and manage drafts. Sending emails is permanently disallowed without human webmail review.

🔐

OS Keystore Security

OAuth tokens are securely stored in macOS Keychain, Windows DPAPI, or Linux Secret Service—never plain text files.

🤖

Prompt-Injection Defense

Untrusted email content is strictly enclosed within standard boundary delimiters to protect LLM agents from injection.

zsh - gmail

$ gmail search "is:unread newer_than:2d" --account work

count: 1

results:

  - id: 18e4f1a2b3c4d5e6

    threadId: 18e4f1a2b3c4d5e6

    from: Alex Rivera <alex@example.com>

    subject: Q3 Planning Review

    snippet: Could you take a look at the attached roadmap proposal...


$ gmail draft reply 18e4f1a2b3c4d5e6 --body "Looks great, approved." --account work

draft_created_not_sent:

  draftId: r-7890123456

  messageId: 18e4f1a2b3c4d5e7

  threadId: 18e4f1a2b3c4d5e6

  to: [alex@example.com]

  subject: Re: Q3 Planning Review

  webUrl: https://mail.google.com/mail/u/0/#drafts?compose=r-7890123456

✓ Draft created successfully. Please open webUrl in browser to review and send.

When To Use Gmail CLI

Guidance for developers, autonomous AI agents, and automated pipelines.

Best-Fit Scenarios

  • Autonomous AI Agent Mailbox Triage: Safely summarize, filter, and extract action items from inboxes with structured JSON and prompt injection markers.
  • Automated Draft Composition: Prepare context-aware replies and new email drafts without risking unintended email transmission.
  • Secure Attachment Harvesting: Download invoices, receipts, and reports with automatic path sanitization and directory traversal defense.
  • Multi-Account Inbox Auditing: Inspect labels, message counts, and unread threads across personal and enterprise accounts with strict --account separation.

When Not to Use

  • When you want automated headless email sending (the CLI guarantees drafts only; human review via Gmail web is required).
  • When you need full interactive TUI email client browsing (use a terminal mail client like Neomutt or Aerc).

Quickstart Workflow

Get configured and productive in less than two minutes.

1

Install

Install the CLI using Cargo or download prebuilt binaries from GitHub Releases.

cargo install --git https://github.com/SpaceCorps/Gmail-Cli
2

Setup

Run gmail setup to initiate the PKCE OAuth loopback flow and secure credentials in your OS vault.

gmail setup --account work
3

Search & Draft

Search unread messages, inspect threads, and compose draft replies safely.

gmail search "is:unread" --account work

v1.0.0 Stable Release

Download pre-compiled standalone binaries for macOS, Linux, and Windows.

🍎 macOS (Apple Silicon)
aarch64-apple-darwin • .tar.gz
Download ↓
🍏 macOS (Intel)
x86_64-apple-darwin • .tar.gz
Download ↓
🐧 Linux (x86_64)
musl static binary • .tar.gz
Download ↓
🪟 Windows (x64)
x86_64-pc-windows-msvc • .zip
Download ↓

View full changelog and SHA256 checksums on GitHub Releases.

Command Reference

Organized by resource category.

# Interactive PKCE OAuth setup (Desktop loopback)
gmail setup --account work

# Setup with explicit client credentials
gmail setup --account work --client-id <id> --client-secret <secret>

# Headless / manual setup for SSH servers
gmail setup --account ci --manual

# List configured accounts
gmail account list

# Remove an account and purge its secrets from keystore
gmail account remove work --yes

# System diagnostics (keystore, clock skew, API reachability)
gmail doctor
gmail doctor --account work
# Search messages (hydrated with snippet, subject, from, date)
gmail search "is:unread newer_than:7d" --account work

# Limit search results (1-50, default 10)
gmail search "from:boss@example.com" --limit 5 --account work

# Fast query without hydrating message bodies
gmail search "label:INBOX" --no-hydrate --account work

# Raw JSON output for machine parsing
gmail search "has:attachment" --account work --json | jq .
# Read message content with untrusted boundary protection
gmail message get <id> --account work

# Request HTML body representation
gmail message get <id> --body-mode html --account work

# Read raw RFC 822 / RFC 2822 / RFC 5322 MIME
gmail message get <id> --body-mode raw --account work

# Read an entire conversation thread
gmail thread get <thread-id> --account work

# Download an attachment safely to a local folder
gmail attachment get <message-id> <attachment-id> --output ./downloads --account work
# Create a new draft (Draft safety: created, NEVER sent!)
gmail draft create --to "team@example.com" --subject "Status Update" --body "Draft text" --account work

# Reply to a message (auto-calculates Re: subject and References)
gmail draft reply <message-id> --body "Thank you for the update." --account work

# Reply-All to all recipients
gmail draft reply <message-id> --reply-all --body "Acknowledged by team." --account work

# List and inspect existing drafts
gmail draft list --account work
gmail draft get <draft-id> --account work

# Update an existing draft
gmail draft update <draft-id> --body "Revised draft content" --account work

# List all labels
gmail label list --account work