DocsCLIco gmail

co gmail

Read, reply, send, and search your own Gmail account right in the terminal — the same Gmail API your agents use, as a command.

Download

This is your mailbox, not the agent's. It needs co auth google once, and it mirrors co outlook command for command.

Quick Start

code
bash
# Connect your Google account (one-time)
co auth google

# Check your inbox (the zero-arg default)
co gmail

# Read message #3 from the inbox list
co gmail read 3

# Send a message
co gmail send alice@example.com "Hello" "Thanks for the meeting today!"

That's the whole surface. Everything below is detail.

Setup

Terminalbash

$co auth google

Opens the Google OAuth flow and saves GOOGLE_* credentials (access token, refresh token, scopes, email) to your project .env and ~/.co/keys.env. Tokens auto-refresh at the start of every command, so you authorize once.

Commands

co gmail — Show the inbox

Terminalbash

$co gmail

$co gmail inbox --last 25

$co gmail inbox --unread

With no subcommand you get your 10 most recent emails — same as co gmail inbox. A green ● marks unread. --last, -n changes the count, --unread, -u filters to unread only.

Emails are numbered, and numbers mean your last listing — co gmail read 3 opens the third row of the table you just saw. Running co gmail again renumbers.

co gmail read <#> — Read one email

Terminalbash

$co gmail read 3

$co gmail read 18f2c9d0a1b2c3d4

Takes a listing number or a full message id. Prints the headers in a panel and the body below it, then marks the email read — only when your token carries gmail.modify; a read-only token skips that step.

co gmail reply <#> <message> — Reply

code
bash
co gmail reply 3 "Sounds good, see you then."
cat reply.txt | co gmail reply 3 -

Threaded — the reply goes back on the original conversation. A message of - reads the body from stdin.

co gmail send <to> <subject> <message> — Send

code
bash
co gmail send alice@example.com "Report" "See notes below."
co gmail send alice@example.com "Report" - < body.txt
co gmail send a@x.com,b@y.com "Update" "Shipping today" --cc lead@x.com

Recipients are comma-separated; --cc and --bcc take the same form. A message of - reads the body from stdin, which is how you send anything long or multi-line without fighting shell quoting.

co gmail sent — Recently sent

Terminalbash

$co gmail sent

$co gmail sent -n 25

A read-only listing — it does not touch the numbering used by read and reply.

co gmail search <query> — Search

code
bash
co gmail search "invoice"
co gmail search "from:alice@example.com is:unread"
co gmail search "subject:meeting after:2026/07/01" -n 25

Takes full Gmail query syntax, not just plain words. Matches are numbered exactly like the inbox, so co gmail read <#> works on search results too.

Piping

In a terminal you get a Rich table with truncated columns. When the output is piped, you get the plain listing with full message ids instead, so scripts and agents never receive a truncated value.

Terminalbash

$co gmail inbox -n 50 | grep "ID:"

Same Functions, in Your Agent

The CLI is a thin wrapper over the Gmail tool — anything co gmail does, your agent can do too:

main.py
python
from connectonion import Agent, Gmail

agent = Agent("assistant", tools=[Gmail()])
agent.input("Any unread mail from Alice?")

Or call the same methods directly:

main.py
python
gmail = Gmail()
gmail.list_inbox(last=10, unread=True)
gmail.list_search("from:alice@example.com")
gmail.send("alice@example.com", "Report", "See attached.")

Troubleshooting

• "Google account not connected" → run co auth google.
• Missing Gmail scopes → run co auth google again to re-consent.
• "No email #N in your last listing" → the number is out of range or the listing changed; run co gmail to refresh the numbering.
• Credentials found in one project but not another → fixed in 1.3.1; older versions read either the project .env or ~/.co/keys.env, never both.

co gmail

Quick Start

Setup

Commands

co gmail — Show the inbox

co gmail read <#> — Read one email

co gmail reply <#> <message> — Reply

co gmail send <to> <subject> <message> — Send

co gmail sent — Recently sent

co gmail search <query> — Search

Piping

Same Functions, in Your Agent

Troubleshooting

See Also

Star us on GitHub