gsuite-manager

name

gsuite-manager

description

This skill should be used when managing Gmail or Google Calendar through the gsuite CLI tool. It applies when the user asks to read, send, search, label, archive, or otherwise manage their Gmail — including messages, threads, labels, drafts, and attachments — or when managing calendar events including listing, creating, updating, deleting, and responding to invitations. Trigger keywords include email, Gmail, inbox, send, draft, label, search mail, unread, archive, attachment, calendar, events, meeting, schedule, RSVP, invite.

Google Workspace Manager via gsuite CLI

Manage Gmail and Google Calendar through the gsuite command-line tool. This skill covers authentication, reading mail, sending emails, organizing with labels, managing drafts, searching, inbox cleanup, and calendar event management.

Prerequisites

The gsuite binary must be installed and available on PATH. To verify:

gsuite --help

If not installed, build from source or download from releases. See the project README for installation instructions.

Authentication

Before any Gmail operation, verify authentication status:

gsuite whoami

If this fails, the user needs to authenticate.

OAuth2 Login

Requires OAuth2 client credentials via environment variable:

# Set credentials (raw JSON or file path)
export GOOGLE_CREDENTIALS='{"installed":...}'
# or
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/oauth2-client.json

# Login (opens browser for OAuth2 consent)
gsuite login

After login, the token is saved per-account at ~/.config/gsuite/tokens/<email>.json.

Multi-Account Support

You can login with multiple Gmail accounts. The most recently logged-in account becomes the active account.

# Login with first account
gsuite login

# Login with another account (opens browser again)
gsuite login

# List all authenticated accounts (* marks active)
gsuite accounts list

# Switch active account
gsuite accounts switch [e-mail]

# Remove an account
gsuite accounts remove [e-mail]

Using a Specific Account

Use --account to run any command as a specific account without switching:

gsuite --account [e-mail] messages list
gsuite --account [e-mail] search "is:unread"

Or set the GSUITE_ACCOUNT environment variable:

export GSUITE_ACCOUNT=[e-mail]
gsuite messages list

Logout

# Logout active account
gsuite logout

# Logout specific account
gsuite logout [e-mail]

Safety Rules

CRITICAL: Confirm with the user before executing any destructive action.

Destructive actions that MUST be confirmed:

• gsuite send — sending an email (cannot be unsent)
• gsuite drafts send — sending a draft (removes it from drafts)
• gsuite drafts delete — permanently deletes a draft
• gsuite labels delete — permanently deletes a label
• gsuite messages modify with --remove-labels — removing labels from messages
• gsuite calendar delete — deletes a calendar event
• gsuite calendar delete --recurring-scope all — deletes ALL instances of a recurring event (requires --yes)
• gsuite calendar create --send-updates all — sends real email invitations to attendees
• gsuite calendar update --send-updates all — sends update notifications to attendees

Safe read-only actions that do NOT need confirmation:

• whoami, messages list, messages get, threads list, threads get
• search, labels list, drafts list, drafts get
• messages get-attachment (downloads a file, low risk)
• accounts list, accounts switch (just changes active account)
• calendar list, calendar get, calendar today, calendar week, calendar calendars

Medium-risk actions — confirm if the scope is large:

• gsuite labels create — creating labels
• gsuite labels update — renaming labels
• gsuite drafts create / drafts update — creating or editing drafts
• gsuite messages modify with --add-labels only — adding labels
• gsuite accounts remove — removes an account and its token
• gsuite logout — removes the active account's token
• gsuite calendar create (without --send-updates all) — creates event without notifying
• gsuite calendar update (without --send-updates all) — modifies event without notifying
• gsuite calendar respond — changes your RSVP status

Output Format

Always use --format json (-f json) when processing results programmatically. JSON mode provides structured output that is easier to parse and chain.

Use text mode (default) when displaying results directly to the user.

Command Reference

For detailed command syntax, flags, and examples, read the reference file at references/commands.md within this skill directory.

Common Workflows

Check Inbox

gsuite messages list --label-ids INBOX -n 20

To see only unread:

gsuite messages list --label-ids INBOX,UNREAD -n 20

Read a Message

gsuite messages get <message-id>

Search for Emails

gsuite search "from:[e-mail] newer_than:7d"
gsuite search "subject:invoice has:attachment"
gsuite search "is:unread in:inbox"

Send an Email

Emails are sent as multipart/alternative (plain text + HTML) for best rendering. The body supports markdown formatting (bold, italic, links, lists, code, strikethrough, tables) which is rendered as HTML. Use \n for line breaks. After confirming with the user:

gsuite send --to "[e-mail]" --subject "Subject" --body "Hello,\n\nHow are you?\nBest regards"

With markdown formatting:

gsuite send -t "[e-mail]" -s "Update" -b "**Important:** Review the *report*.\n\n- Item one\n- Item two\n\nVisit [Google](https://google.com)"

With attachments:

gsuite send -t "[e-mail]" -s "Report" -b "See attached.\n\nThanks" --attach report.pdf

Organize with Labels

List existing labels to find IDs:

gsuite labels list

Create a new label:

gsuite labels create -n "Project/Alpha"

Apply a label to a message:

gsuite messages modify <message-id> --add-labels Label_123

Mark as read:

gsuite messages modify <message-id> --remove-labels UNREAD

Archive (remove from inbox):

gsuite messages modify <message-id> --remove-labels INBOX

Find TODOs and Action Items

Search for emails that likely contain action items:

gsuite search "subject:(todo OR action OR follow up OR action required) newer_than:30d" -n 50

Then read individual messages to extract the actual tasks:

gsuite messages get <message-id>

Clean Up Inbox

To mark multiple messages as read, archive, or label them, first search or list to get message IDs, then modify each one. Chain operations for efficiency:

# Get unread inbox messages as JSON for processing
gsuite messages list --label-ids INBOX,UNREAD -n 50 -f json

Then for each message ID, apply the appropriate action.

Manage Drafts

gsuite drafts list
gsuite drafts create -t "[e-mail]" -s "Subject" -b "Body"
gsuite drafts send <draft-id>      # Confirm first!
gsuite drafts delete <draft-id>    # Confirm first!

Download Attachments

First view the message to see attachment IDs:

gsuite messages get <message-id>

Then download:

gsuite messages get-attachment <message-id> <attachment-id> --output ./downloads/file.pdf

Calendar Workflows

Check Today's Schedule

gsuite calendar today

Check This Week's Events

gsuite calendar week

List Upcoming Events

gsuite calendar list
gsuite calendar list --after today --before +7d -n 50
gsuite calendar list --query "standup" --after today

View Event Details

gsuite calendar get <event-id>
gsuite calendar get <event-id> -f json

Create a Meeting

After confirming with the user:

# Simple 1-hour meeting (default duration)
gsuite calendar create --summary "Team Meeting" --start "2026-03-15 09:00"

# Meeting with explicit duration
gsuite calendar create --summary "Standup" --start "2026-03-15 09:00" --duration 30m

# All-day event
gsuite calendar create --summary "Company Holiday" --start 2026-12-25 --all-day

# Meeting with attendees (sends invitations)
gsuite calendar create --summary "Review" --start "2026-03-15 14:00" --duration 1h \
  --attendees "[e-mail],[e-mail]" --send-updates all

# Recurring weekly meeting
gsuite calendar create --summary "1:1" --start "2026-03-15 10:00" --duration 30m \
  --rrule "FREQ=WEEKLY;BYDAY=MO"

Update an Event

# Change title
gsuite calendar update <event-id> --summary "New Title"

# Reschedule
gsuite calendar update <event-id> --start "2026-03-20 10:00" --end "2026-03-20 11:00"

# Add attendees and notify them
gsuite calendar update <event-id> --add-attendees "[e-mail]" --send-updates all

# Update all instances of a recurring event
gsuite calendar update <event-id> --summary "New Name" --recurring-scope all

RSVP to an Event

gsuite calendar respond <event-id> --status accepted
gsuite calendar respond <event-id> --status declined --comment "Out of office"
gsuite calendar respond <event-id> --status tentative

Delete an Event

After confirming with the user:

gsuite calendar delete <event-id>

# Delete all instances of a recurring event (requires --yes)
gsuite calendar delete <event-id> --recurring-scope all --yes

List Available Calendars

gsuite calendar calendars

Date/Time Input Formats

Calendar commands accept flexible date/time formats:

Format	Example	Description
RFC3339	2026-03-15T09:00:00-07:00	Full timestamp with timezone
Date + time	2026-03-15 09:00	Date and time (local timezone)
Date only	2026-03-15	Start of day
Time only	09:00	Today at that time
today	today	Start of today
tomorrow	tomorrow	Start of tomorrow
Day name	monday	Next occurrence of that day
Relative	+3d	3 days from now

Troubleshooting

"no authenticated accounts" — No accounts logged in. Run gsuite login.

"no token for account X" — Account is in the store but token is missing. Run gsuite login to re-authenticate.

"authentication failed" — Credentials are invalid or expired. Try gsuite logout then gsuite login again.

"Gmail API error: 403" — Insufficient permissions. The OAuth2 scope may not include the required Gmail scope.

"Gmail API error: 404" — Message or label not found. The ID may be wrong or the item was already deleted.

"account not found" — The email passed to accounts switch or accounts remove doesn't match any authenticated account. Check with gsuite accounts list.

"calendar permission not granted" — The OAuth2 token doesn't include calendar scopes. Run gsuite login to re-authenticate with calendar access.

"you are not listed as an attendee" — Trying to RSVP to an event where you are not in the attendees list. Check the event with gsuite calendar get <id>.