Secure Gmail CLI for AI Agents
Lock down Gmail API access from your terminal. One npm install, one OAuth flow, and your AI agents only see what your rules allow. No dashboards, no GUIs, just fast and scriptable security.
How PortEden Protects You
Six layers of security between AI and your data.
Config-as-Code Rules
Define Gmail security rules in a declarative config file, version them in git, and deploy with the same workflow you use for application code.
Terminal-Based Visibility Controls
Set what agents can see from the command line: full content, headers only, or redacted bodies, with changes taking effect instantly.
Scriptable Action Limits
Restrict agents to read-only or draft-only through config flags, with the CLI enforcing limits on every request.
Contact Rules via CLI Flags
Block agents from accessing emails from specific senders or domains, with rules taking effect immediately from the command line or a config file.
What a real Gmail CLI session looks like
Most teams discover the limits of gmail.modify the hard way: an agent that was supposed to draft replies ends up with read, send, and delete on every label in the mailbox. The Secure Gmail CLI fixes that without rewriting how your agent talks to Gmail. Here's the actual install + first-run sequence:
$ npx @porteden/cli connect gmail
→ Browser opens to accounts.google.com
→ Granting "Read, modify, send" to PortEden CLI...
✓ Token stored in OS keyring (gmail:adam@porteden.com)
✓ Wrote default config to ~/.porteden/gmail.yamlThe generated ~/.porteden/gmail.yaml ships with safe defaults — read-only, no labels excluded — and is immediately overridable. Gmail-specific rules that the provider-agnostic config can't express:
agents:
summarizer:
mode: read
include_labels: ["INBOX", "Clients/*"]
exclude_labels: ["HR", "Legal", "Investors"]
redact: ["X-Original-Sender", "Received", "Authentication-Results"]
sender_allowlist_domain: ["porteden.com", "*.tagatime.com"]
body_max_kb: 32Troubleshooting OAuth refresh-token expiry
Gmail refresh tokens silently expire after 7 days when the Google Cloud project is in "Testing" mode (a common gotcha during pilot rollouts). The CLI surfaces this with porteden auth status instead of letting an agent see invalid_grant mid-request. Move the project to "In production" in the OAuth consent screen to get indefinite-lifetime refresh tokens.
Why not just use gmail-api-python-client?
You can — and many teams start there. The line you hit is when you need to enforce label exclusions, header redaction, and per-agent rate limits across three different agent runtimes (Claude Desktop, ChatGPT, an internal LangChain app). The CLI puts that policy in one config file and one audit log instead of three forks of the same wrapper.
Get Started in 3 Steps
Install — CLI or MCP
Add the PortEden CLI via npm install, or connect the cloud MCP connector to your AI client — either path gets the same filtering.
Authenticate and Configure
Connect your Gmail account with a single OAuth command, then define your rules in a config file.
Deploy Your Rules
Point your AI agents to the PortEden proxy so every Gmail API call is filtered through your config.
Without vs. With PortEden
Without PortEden
- Raw Gmail OAuth tokens stored in environment variables and CI secrets
- Access rules managed through Google's point-and-click admin console
- No version control for security policies across environments
- Each team configures Gmail scopes independently with no central policy
With PortEden
- OAuth tokens stored securely by the CLI, never exposed to agents
- Rules defined in config files, versioned in git, deployed via CI/CD
- Consistent security policy across dev, staging, and production
- One config file governs all agents accessing Gmail