← Wiki
2026-11-07 concept gmailgoogle-workspaceclioauthagentssecurity

Gmail from the terminal: several mailboxes for a coding agent

Short version

gws is the Google Workspace CLI (npm @googleworkspace/cli, v0.22.5 here). It talks to the Gmail API with your own OAuth client, so an agent can run gws gmail ... like any shell command. To keep several mailboxes apart, give each one its own config directory and a three-line wrapper (gws-personal, gws-work). Log in with --readonly. Publish the OAuth app (Testing to In production) or the token dies every 7 days.

For a coding agent

Give your agent this page, or install the skill that holds the same steps in agent form:

# any agent (Claude Code, Cursor, Codex, Gemini CLI, ...)
npx skills add fortunto2/solo-factory --skill solo-gmail-cli -g
# or Claude Code, the whole solo plugin
claude plugin marketplace add https://github.com/fortunto2/solo-factory
claude plugin install solo@solo --scope user

Skill source: https://github.com/fortunto2/solo-factory/tree/main/skills/gmail-cli. The agent installs gws, writes the per-mailbox wrappers and runs the reads. Only the Google Cloud Console clicks (project, Desktop OAuth client, Branding, Publish app) and the consent screen need your hands; it stops and says when.

Definition

One OAuth client (a client_secret.json), N config directories, N logins. The CLI picks the mailbox by the environment variable GOOGLE_WORKSPACE_CLI_CONFIG_DIR. There is no --account flag, and asking for another address through userId gives “Delegation denied”. The directory is the only switch.

Steps

1. Install

npm install -g @googleworkspace/cli
gws --version        # 0.22.5 here

2. Google Cloud project and OAuth client (browser, once)

Done by hand: the API cannot create a Desktop client.

  1. console.cloud.google.com, create a project (my-project).
  2. APIs and Services, Library: enable Gmail API (add Drive or Calendar if you want them).
  3. Google Auth Platform, Branding: fill it (see the key lesson below).
  4. Clients, Create client, type Desktop app, Download JSON.

One project can hold the Gmail client and a YouTube client, see youtube-channels-from-terminal.

3. One config directory per mailbox

mkdir -p ~/.config/gws-personal
cp ~/Downloads/client_secret_*.json ~/.config/gws-personal/client_secret.json

The same client_secret.json can be copied into every directory.

4. One wrapper per mailbox

cat > ~/.local/bin/gws-personal <<'SH'
#!/usr/bin/env bash
exec env GOOGLE_WORKSPACE_CLI_CONFIG_DIR="$HOME/.config/gws-personal" gws "$@"
SH
chmod +x ~/.local/bin/gws-personal

Repeat with another name and directory for every box (gws-work, gws-shop). The agent now says gws-work ... and cannot land in the wrong mailbox by accident.

5. Log in read-only

gws-personal auth login --readonly
gws-personal auth status      # check which mailbox this really is

A browser opens. Pick the account that matches the wrapper. On the “Google hasn’t verified this app” screen: Advanced, Go to your app. This is expected for a personal app.

Check auth status before every search session. An empty result from the wrong mailbox looks exactly like “nothing found”: one search for a vendor came back empty only because it went to the wrong box.

6. Read commands

# list by Gmail query (newest first)
gws-personal gmail users messages list \
  --params '{"userId":"me","q":"from:[email protected] after:2026/01/01","maxResults":20}'

# unread summary with sender, subject, date
gws-personal gmail +triage --max 20 --format table

# one message: body as text, or headers too
gws-personal gmail +read --id MESSAGE_ID --headers

# full JSON, with attachment ids in payload.parts[]
gws-personal gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID","format":"full"}'

# one attachment (returns base64url data)
gws-personal gmail users messages attachments get \
  --params '{"userId":"me","messageId":"MESSAGE_ID","id":"ATTACHMENT_ID"}'

Useful query pieces: from:me, subject:"exact phrase", has:attachment, after:2025/05/01 before:2025/07/01. Gmail returns the newest first, so a query without before: hides early years. Dig in periods.

Each get is one API call; reading 16 messages took about 40 seconds. Search wide without bodies, then read 3 to 6 messages.

7. Rules for the agent

Key lesson: Testing status kills the token in 7 days

Measured 7 Nov 2026: an OAuth app left in Testing publishing status issues refresh tokens that expire after 7 days. Both the Gmail and the YouTube token died this way, with invalid_grant every week.

Fix:

  1. Google Cloud Console, Google Auth Platform, Audience, Publish app (Testing to In production).
  2. The button stays disabled with “To publish your app, you must complete your configuration on the Branding page” until Branding has:
    • an app name without Google trademarks (a name containing “Gmail” had to be renamed),
    • an application home page,
    • a privacy policy link,
    • that domain listed under Authorised domains.
  3. Do not upload a logo. A logo forces Google verification.
  4. Publish, then run auth login once more. The old token is dead; the new one does not expire weekly.

Personal use stays unverified: the consent screen says “Google hasn’t verified this app” (Advanced, Go to app), and the user cap is 100. For your own mailboxes that is fine.

Pitfalls

Numbers

Related

Learned from

Session 2026-11-07 (OAuth Testing to Production), and the earlier gmail-dig work across four mailboxes.

Related