version: "1.0.1" name: gmcli description: Gmail CLI for searching emails, reading threads, sending messages, managing drafts, and handling labels and attachments. Use when the user asks about their email or inbox, or wants to send, archive, label, or download from Gmail.

Gmail CLI

Command-line interface for Gmail operations.

Usage

Run gmcli --help for full command reference.

Common operations:

• gmcli <email> search "<query>" - Search emails using Gmail query syntax
• gmcli <email> thread <threadId> - Read a thread with all messages
• gmcli <email> send --to <emails> --subject <s> --body <b> - Send email
• gmcli <email> labels list - List all labels
• gmcli <email> drafts list - List drafts

Wrong commands — do not use

These commands do not exist and will fail immediately:

Archiving and labelling

There is no archive command. Archive by removing the INBOX label:

# Correct — comma-separated in ONE flag:
gmcli <email> labels <threadId> --remove INBOX,UNREAD
gmcli <email> labels <threadId> --add "House Search" --remove INBOX,UNREAD
 
# WRONG — repeating the flag silently drops all but the last value:
# gmcli <email> labels <threadId> --remove INBOX --remove UNREAD  ← leaves email in inbox

Additional rules:

• `labels` takes thread IDs, not message IDs. A message ID from a

multi-message thread returns Requested entity was not found. Get the thread ID from search or thread output.

• Never pipe these commands to 2>/dev/null or chain them with ;. Errors are

the only signal that the archive did not happen. Check the printed <threadId>: ok.

• Verify with gmcli <email> search "in:inbox" when it matters.

Troubleshooting

If you get an invalid_grant error, the OAuth token has expired. Re-authenticate by removing and re-adding the account:

gmcli accounts remove <email> && gmcli accounts add <email>