← Back to Gmail CLI

About Gmail CLI

Gmail CLI is a high-performance, open-source command-line tool and programmatic automation interface designed specifically for the Google Gmail API (v1). Maintained under the SpaceCorps open-source engineering collective, the project originated to provide developers and autonomous AI agents with a single, standalone binary capable of operating seamlessly across macOS, Linux, and Windows without runtime dependencies or interpreter overhead.

Project Mission & Origins

Modern terminal workflows and AI-driven automation demand rapid feedback loops and absolute security. The original prototype CLI was implemented as a .NET console application by Niels Bosma (nielsbosma/Gmail.Console). While functional, autonomous coding assistants and shell pipelines benefit immensely from static binaries that start in 1 to 3 milliseconds without managed runtime startup latencies. In 2026, the CLI was completely re-architected in native Rust 2024 to achieve instant startup, predictable resource utilization, and zero external runtime dependencies.

Architectural Principles & Safety Guarantees

Gmail CLI is built around four uncompromising principles: safety, determinism, prompt-injection defense, and speed.

• Draft Safety Guarantee: The CLI deliberately does not implement an email sending command. It can create, reply to, update, and delete drafts, but human confirmation via the Gmail web interface is strictly required before any email is dispatched.
• Prompt-Injection Mitigation: Untrusted external email content (subject lines, sender headers, message bodies, attachment names) is strictly demarcated with clear boundary markers (--- untrusted email content begins --- / --- untrusted email content ends ---) to protect LLM agents from adversarial prompt injections.
• OS Keystore Protection: Unlike conventional scripts that store plain-text OAuth refresh tokens on disk, Gmail CLI integrates natively with host operating system credential vaults—such as macOS Keychain, Windows DPAPI, and the Linux Secret Service daemon.
• Strict Account Scoping: To prevent catastrophic accidental operations across personal, work, and client inboxes, all mailbox commands require an explicit --account flag. There is no ambiguous default account.

Specification & Compatibility

Every command and flag in the CLI is grounded directly in the official Google Gmail REST API v1 specification, providing full support for message search, thread hydration, attachment downloading with directory traversal defense, label management, draft composition, and comprehensive environment diagnostics.