Google Personal Assistant

A comprehensive skill for managing Google Workspace services via the

gog

When to Use This Skill

• Triaging and processing email inbox
• Scheduling meetings and managing calendar events
• Finding availability across multiple calendars
• Searching and organizing Google Drive documents
• Managing task lists and to-dos
• Looking up and managing contacts
• Reading/writing data in Google Sheets
• Exporting Docs, Slides, or Sheets
• Setting focus time or out-of-office status

Prerequisites

Ensure

gog

# Check installation
gog version

# Check authentication status
gog auth status

# Verify account access
gog people me

# Add a new account if needed
gog auth add your@email.com --services=all

Quick Start

Gmail

# Search unread emails
gog gmail search "is:unread" --max=20

# Search from specific sender
gog gmail search "from:boss@company.com newer_than:7d"

# Send an email
gog gmail send --to="recipient@example.com" --subject="Subject" --body="Message body"

# Reply to a thread
gog gmail send --reply-to-message-id=MESSAGE_ID --body="Reply text"

# Get message details
gog gmail get MESSAGE_ID

Calendar

# View today's events
gog calendar events --today

# View this week
gog calendar events --week

# Create an event with Google Meet
gog calendar create primary \
  --summary="Team Sync" \
  --from="2026-01-15T14:00:00-08:00" \
  --to="2026-01-15T15:00:00-08:00" \
  --attendees="person1@example.com,person2@example.com" \
  --with-meet

# Check availability
gog calendar freebusy "person1@example.com,person2@example.com" \
  --from="2026-01-15T09:00:00Z" --to="2026-01-15T17:00:00Z"

# Find scheduling conflicts
gog calendar conflicts --week

Drive

# List files in root
gog drive ls

# Search for documents
gog drive search "quarterly report"

# Download a file
gog drive download FILE_ID

# Upload a file
gog drive upload /path/to/file.pdf --parent=FOLDER_ID

# Get shareable URL
gog drive url FILE_ID

Tasks

# List task lists
gog tasks lists list

# View tasks in default list
gog tasks list @default

# Add a task
gog tasks add @default --title="Review report" --due="2026-01-15"

# Mark task complete
gog tasks done @default TASK_ID

Sheets

# Read a range
gog sheets get SPREADSHEET_ID "Sheet1!A1:D10"

# Update values
gog sheets update SPREADSHEET_ID "Sheet1!A1" "Value1" "Value2"

# Append a row
gog sheets append SPREADSHEET_ID "Sheet1!A:D" "Col1" "Col2" "Col3" "Col4"

Gmail Search Syntax

Gmail search is powerful. Here are the essential operators:

Sender & Recipient

from:

from:boss@company.com

to:

to:team@company.com

cc:

cc:manager@company.com

bcc:

bcc:archive@company.com

Status & Labels

is:unread

is:unread

is:read

is:read

is:starred

is:starred

is:important

is:important

is:snoozed

is:snoozed

label:

label:work

in:inbox

in:inbox

in:sent

in:sent

in:drafts

in:drafts

in:trash

in:trash

in:spam

in:spam

in:anywhere

in:anywhere

Content & Subject

subject:

subject:urgent

"exact phrase"

"quarterly report"

has:attachment

has:attachment

filename:

filename:pdf

filename:

filename:report.xlsx

Date & Time

newer_than:

newer_than:7d

older_than:

older_than:1y

after:

after:2026/01/01

before:

before:2026/12/31

Units for newer_than/older_than:

d

m

y

Size

larger:

larger:5M

smaller:

smaller:100K

Units:

K

M

Categories

category:primary

category:primary

category:social

category:social

category:promotions

category:promotions

category:updates

category:updates

category:forums

category:forums

Boolean Operators

AND

from:alice subject:report

OR

from:alice OR from:bob

-

-category:promotions

()

(from:alice OR from:bob) is:unread

{}

{from:alice from:bob}

Example Queries

# Unread from VIPs this week
gog gmail search "is:unread from:(boss@company.com OR ceo@company.com) newer_than:7d"

# Large attachments
gog gmail search "has:attachment larger:10M"

# Urgent subjects excluding promotions
gog gmail search "subject:(urgent OR asap OR EOD) -category:promotions is:unread"

# Contracts from legal team
gog gmail search "from:legal@company.com subject:contract has:attachment filename:pdf"

# All messages in a thread (use thread ID from search results)
gog gmail thread get THREAD_ID

See references/gmail-search-syntax.md for complete operator reference.

Drive Search Syntax

Drive search uses a query language for precise file finding:

Basic Operators

name contains

name contains 'report'

fullText contains

fullText contains 'budget'

mimeType =

mimeType = 'application/pdf'

Date Filters

modifiedTime >

modifiedTime > '2026-01-01'

modifiedTime <

modifiedTime < '2026-01-01'

createdTime >

createdTime > '2026-01-01'

viewedByMeTime >

viewedByMeTime > '2026-01-01'

Ownership & Sharing

'email' in owners

'me' in owners

'email' in writers

'user@example.com' in writers

'email' in readers

'user@example.com' in readers

sharedWithMe

sharedWithMe

Properties

starred

starred

trashed = false

trashed = false

'folderId' in parents

'FOLDER_ID' in parents

Common MIME Types

application/vnd.google-apps.document

application/vnd.google-apps.spreadsheet

application/vnd.google-apps.presentation

application/vnd.google-apps.form

application/vnd.google-apps.folder

application/pdf

application/vnd.openxmlformats-officedocument.wordprocessingml.document

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Boolean Operators

• and

  - Both conditions must match

• or

  - Either condition matches

• not

  - Negate condition

Example Queries

# Recent docs mentioning Q4
gog drive search "fullText contains 'Q4' and modifiedTime > '2026-01-01'"

# All spreadsheets shared with me
gog drive search "sharedWithMe and mimeType = 'application/vnd.google-apps.spreadsheet'"

# PDFs I own
gog drive search "'me' in owners and mimeType = 'application/pdf'"

# Files modified this week
gog drive search "modifiedTime > '2026-01-03'"

# Documents in specific folder
gog drive ls --parent=FOLDER_ID

# Starred presentations
gog drive search "starred and mimeType = 'application/vnd.google-apps.presentation'"

See references/drive-search-syntax.md for complete query reference.

PA/CoS Workflows

Morning Inbox Triage

# 1. Check unread counts by label
gog gmail labels list --json | jq '.[] | select(.messagesUnread > 0) | {name, unread: .messagesUnread}'

# 2. Review unread from priority senders
gog gmail search "is:unread from:(boss@company.com OR vip@client.com)" --max=20

# 3. Check for urgent subjects
gog gmail search "is:unread subject:(urgent OR asap OR EOD OR \"action required\")" --max=10

# 4. Review threads needing response (excludes noise)
gog gmail search "is:unread in:inbox -category:updates -category:promotions -category:social" --max=30

# 5. Check for emails with attachments requiring action
gog gmail search "is:unread has:attachment newer_than:2d" --max=15

Schedule a Meeting

# 1. Find availability for attendees
gog calendar freebusy "person1@company.com,person2@company.com" \
  --from="2026-01-15T09:00:00-08:00" \
  --to="2026-01-15T17:00:00-08:00"

# 2. Check your own conflicts
gog calendar conflicts --days=7

# 3. Create the meeting
gog calendar create primary \
  --summary="Project Kickoff" \
  --from="2026-01-15T14:00:00-08:00" \
  --to="2026-01-15T15:00:00-08:00" \
  --attendees="person1@company.com,person2@company.com" \
  --description="Agenda:\n1. Project overview\n2. Timeline review\n3. Action items" \
  --location="Conference Room A" \
  --with-meet \
  --reminder="popup:15m"

# 4. Send follow-up email with details
gog gmail send \
  --to="person1@company.com,person2@company.com" \
  --subject="Meeting Scheduled: Project Kickoff - Jan 15 at 2pm" \
  --body="Hi team,

I've scheduled our project kickoff meeting for Wednesday, January 15th at 2:00 PM.

Location: Conference Room A (Google Meet link in calendar invite)

Agenda:
1. Project overview
2. Timeline review
3. Action items

Please let me know if you have any conflicts.

Best regards"

Weekly Calendar Prep

# 1. View the week ahead
gog calendar events --week

# 2. Check all calendars for the week
gog calendar events --week --all

# 3. Find and resolve conflicts
gog calendar conflicts --week

# 4. Check team availability (for group)
gog calendar team engineering@company.com --week

# 5. Block focus time
gog calendar focus-time \
  --from="2026-01-16T09:00:00-08:00" \
  --to="2026-01-16T12:00:00-08:00"

# 6. Set out of office (if needed)
gog calendar out-of-office \
  --from="2026-01-20" \
  --to="2026-01-21" \
  --summary="Out of office - personal day"

# 7. Set working location
gog calendar working-location \
  --from="2026-01-17" \
  --to="2026-01-17" \
  --type="home"

Document Search & Organization

# Find all docs from a project
gog drive search "fullText contains 'Project Alpha'"

# List recent docs you created
gog drive search "'me' in owners and modifiedTime > '2026-01-01'" --max=50

# Find docs shared by specific person
gog drive search "'colleague@company.com' in writers"

# Find presentation decks
gog drive search "mimeType = 'application/vnd.google-apps.presentation' and modifiedTime > '2025-10-01'"

# Download a doc as PDF
gog docs export DOC_ID --format=pdf --output="./report.pdf"

# Read doc contents (plain text for quick review)
gog docs cat DOC_ID

# Export spreadsheet as Excel
gog sheets export SPREADSHEET_ID --format=xlsx --output="./data.xlsx"

# Get shareable link
gog drive url FILE_ID
gog drive share FILE_ID --role=reader --type=anyone

Daily Task Management

# 1. List all task lists
gog tasks lists list

# 2. View all tasks in default list
gog tasks list @default

# 3. View tasks due today
gog tasks list @default --due-max="$(date -u +%Y-%m-%dT23:59:59Z)"

# 4. Add a new task with due date
gog tasks add @default \
  --title="Review Q4 financials" \
  --due="2026-01-15" \
  --notes="Check revenue projections and expense reports"

# 5. Complete a task
gog tasks done @default TASK_ID

# 6. Reopen a completed task
gog tasks undo @default TASK_ID

# 7. Delete a task
gog tasks delete @default TASK_ID

# 8. Clear all completed tasks
gog tasks clear @default

Contact Lookup

# Search for a contact
gog contacts search "John Smith"

# List all contacts
gog contacts list --max=100

# Get contact details
gog contacts get RESOURCE_NAME

# Create a new contact
gog contacts create \
  --given="Jane" \
  --family="Doe" \
  --email="jane.doe@example.com" \
  --phone="+1-555-123-4567"

# Search directory (Workspace)
gog contacts directory search "engineering"

See references/common-workflows.md for more workflow recipes.

Command Reference

Gmail Commands

gmail search <query>

--max

--oldest

--page

gmail get <messageId>

--format=full|metadata|raw

gmail send

--to

--cc

--bcc

--subject

--body

--attach

gmail thread get <id>

gmail thread modify <id>

--add-labels

--remove-labels

gmail labels list

gmail labels get <name>

gmail labels modify <ids>

--add

--remove

gmail attachment <msgId> <attId>

gmail url <threadId>

gmail batch delete <ids>

gmail drafts list

gmail drafts create

Calendar Commands

calendar calendars

calendar events [calId]

--from

--to

--today

--week

--all

calendar event <calId> <eventId>

calendar create <calId>

--summary

--from

--to

--attendees

--with-meet

calendar update <calId> <eventId>

calendar delete <calId> <eventId>

calendar freebusy <calendars>

--from

--to

calendar conflicts

--week

--days

calendar search <query>

calendar respond <calId> <eventId>

--status=accepted|declined|tentative

calendar focus-time

--from

--to

calendar out-of-office

--from

--to

calendar working-location

--from

--to

--type

calendar team <groupEmail>

Drive Commands

drive ls

--parent

drive search <query>

--max

drive get <fileId>

drive download <fileId>

--output

drive upload <path>

--name

--parent

drive mkdir <name>

--parent

drive delete <fileId>

drive move <fileId>

--parent

drive rename <fileId> <name>

drive share <fileId>

--role

--type

--email

drive unshare <fileId> <permId>

drive permissions <fileId>

drive url <fileId>

drive copy <fileId> <name>

Sheets Commands

sheets get <id> <range>

sheets update <id> <range> [vals]

--input=RAW|USER_ENTERED

sheets append <id> <range> [vals]

--input

sheets clear <id> <range>

sheets metadata <id>

sheets create <title>

sheets copy <id> <title>

sheets export <id>

--format=pdf|xlsx|csv

Docs Commands

docs cat <docId>

docs export <docId>

--format=pdf|docx|txt

docs info <docId>

docs create <title>

docs copy <docId> <title>

Slides Commands

slides export <id>

--format=pdf|pptx

slides info <id>

slides create <title>

slides copy <id> <title>

Tasks Commands

tasks lists list

tasks list <listId>

--due-min

--due-max

--show-completed

tasks add <listId>

--title

--due

--notes

tasks update <listId> <taskId>

tasks done <listId> <taskId>

tasks undo <listId> <taskId>

tasks delete <listId> <taskId>

tasks clear <listId>

Contacts Commands

contacts search <query>

contacts list

--max

contacts get <resourceName>

contacts create

--given

--family

--email

--phone

contacts update <resourceName>

contacts delete <resourceName>

contacts directory search

Groups Commands

groups list

groups members <groupEmail>

People Commands

people me

Global Flags

All

gog

--json

--plain

--account=EMAIL

--force

--no-input

--verbose

--color=<auto|always|never>

Multi-Account Usage

# Use specific account for a command
gog gmail search "is:unread" --account=work@company.com

# List available accounts
gog auth list

JSON Output for Scripting

# Get unread count for inbox
gog gmail labels get INBOX --json | jq '.messagesUnread'

# Extract event IDs from today
gog calendar events --today --json | jq '.[].id'

# List file IDs from search
gog drive search "budget" --json | jq '.[].id'

# Process email subjects
gog gmail search "is:unread" --json | jq '.[].snippet'

Best Practices

Efficient Searching

1. Start narrow, then broaden - Begin with specific queries, add filters if too many results
2. Use date filters -

   newer_than:

   reduces noise dramatically
3. Combine operators -

   is:unread from:boss newer_than:7d

   is better than browsing
4. Use

   --max

   - Limit results when exploring:

   --max=10

Calendar Management

1. Always check freebusy before scheduling meetings with others
2. Use

   --with-meet

   for remote meetings to auto-create video link
3. Set reminders -

   --reminder="popup:15m"

   for important meetings
4. Block focus time proactively to protect deep work

Drive Organization

1. Use folder IDs - Store frequently-used folder IDs for quick access
2. Search by content -

   fullText contains

   finds docs even if filename is unclear
3. Filter by MIME type - Narrow to specific doc types
4. Export early - Download important docs as PDF for offline access

Automation Tips

1. Use

   --json

   for scripting - Parse with jq
2. Use

   --plain

   for simple scripts - Tab-separated, no colors
3. Use

   --no-input

   in CI - Prevents hangs on prompts
4. Store IDs - Calendar, folder, and task list IDs for reuse

Reference Files

• Gmail Search Syntax - Complete query operator reference
• Drive Search Syntax - Complete Drive query reference
• Calendar Scheduling - Event creation, time formats, RRULE
• Common Workflows - Extended PA/CoS workflow recipes