Gogcli

gogcli

Command-line interface for Google Workspace and consumer Google services. Binary name: gog.

First Step: Check Account

Run gog auth list at the start of every session to check available accounts:

gog auth list

Account selection:

• --account <email|alias> flag on any command
• GOG_ACCOUNT environment variable sets default
• If only one account is stored, it is used automatically

List configured aliases:

gog auth alias list

Flag Placement

Always place flags after the subcommand, not between gog and the command group. This ensures command prefix matching works correctly for permissions.

# Correct:
gog gmail search 'is:unread' --account work --json
gog calendar events --today --account personal

# Wrong:
gog --account work gmail search 'is:unread'

Output Modes

Always use --json for search and list commands. The default table output trims columns to fit the terminal, losing data. JSON returns complete results.

gog gmail search 'newer_than:7d' --json                   # JSON (complete data)
gog gmail search 'newer_than:7d' --json --results-only    # JSON without envelope
gog gmail search 'newer_than:7d' --json --select=id,subject  # Select fields
gog gmail search 'newer_than:7d' --plain                  # Stable TSV (for piping)
gog gmail search 'newer_than:7d'                          # Rich TTY (truncates columns)

Global Flags

Discovering Flags

This skill covers the most common usage patterns. For full flag details on any command, run --help:

gog gmail send --help
gog calendar create --help
gog drive upload --help

Gmail Search

Search Threads

gog gmail search 'newer_than:7d'                     # Last 7 days
gog gmail search 'from:alice@example.com'             # From sender
gog gmail search 'is:unread' --max 20                 # Unread, limit 20
gog gmail search 'has:attachment newer_than:30d'       # With attachments
gog gmail search 'subject:invoice' --all              # All pages
gog gmail search 'in:sent newer_than:1d' --json       # JSON output
gog gmail search 'label:important' --oldest           # Show first message date
gog gmail search 'query' --fail-empty                 # Exit code 3 if no results

Key flags: --max (default 10), --all (all pages), --fail-empty (exit code 3 if no results)

Search Messages (individual messages, not threads)

gog gmail messages search 'newer_than:7d'             # Message-level results
gog gmail messages search 'from:me' --include-body    # Include message body
gog gmail messages search 'is:unread' --max 50 --json

Key additional flag: --include-body (includes decoded message body in output)

Read Thread / Message

gog gmail thread get <threadId>                       # Full thread with all messages
gog gmail thread get <threadId> --full                 # Show full message bodies
gog gmail thread get <threadId> --download             # Download attachments
gog gmail thread get <threadId> --download --out-dir ./attachments
gog gmail get <messageId>                              # Single message
gog gmail get <messageId> --format metadata            # Metadata only
gog gmail url <threadId>                               # Print Gmail web URL

Calendar Events

List Events

gog calendar events                                   # Primary calendar (default)
gog calendar events --today                            # Today only
gog calendar events --tomorrow                         # Tomorrow only
gog calendar events --week                             # This week (Mon-Sun)
gog calendar events --days 3                           # Next 3 days
gog calendar events --from today --to friday           # Relative dates
gog calendar events --from 2025-01-01 --to 2025-01-08 # Absolute dates
gog calendar events --all                              # All calendars
gog calendar events --weekday                          # Include day-of-week columns
gog calendar events <calendarId> --today               # Specific calendar
gog calendar events --query "standup"                  # Free text search

Run gog calendar events --help for full flag list.

Search Events

gog calendar search "meeting" --today
gog calendar search "standup" --days 30
gog calendar search "quarterly" --from 2025-01-01 --to 2025-03-31 --max 50

Get Single Event

gog calendar event <calendarId> <eventId>
gog calendar event <calendarId> <eventId> --json       # JSON with timezone info

List Calendars

gog calendar calendars

Drive Search

List Files

gog drive ls                                          # Root folder (default max 20)
gog drive ls --parent <folderId>                      # Specific folder
gog drive ls --max 50                                 # More results
gog drive ls --no-all-drives                          # My Drive only (excludes shared)
gog drive ls --query "mimeType='application/pdf'"     # Drive query filter

Key flags: --max (default 20), --parent (folder ID), --no-all-drives (My Drive only)

Search Files

gog drive search "invoice"                            # Full-text search
gog drive search "budget report" --max 50
gog drive search "mimeType = 'application/pdf'" --raw-query  # Drive query language
gog drive search "quarterly" --no-all-drives          # My Drive only

Key flags: --max (default 20), --raw-query (use Drive query language directly)

Get / Download

gog drive get <fileId>                                                   # File metadata (check mimeType)
gog drive download <fileId> --format md --out /tmp/gdoc-fileid.md        # Export Google Doc as markdown
gog drive download <fileId> --format pdf --out /tmp/gdoc-fileid.pdf      # Export as PDF
gog drive url <fileId>                                                   # Print web URL

Format options by file type:

• Google Docs: md (best for reading), pdf, docx, txt
• Google Sheets: csv, xlsx, pdf
• Google Slides: pptx, pdf
• Google Drawings: png, pdf

When you need to read a Google Doc's content, prefer --format md. It preserves headings, bold/italic, links, tables, and lists. Plain text (txt) strips all formatting.

Sheets Read

To read a spreadsheet, first get sheet names with metadata, then read with an A1 range:

gog sheets metadata <spreadsheetId>                       # Discover sheet names
gog sheets get <spreadsheetId> 'SheetName!A1:Z100'        # Read values (range required)
gog sheets get <spreadsheetId> 'SheetName!A:Z'            # All rows in columns A-Z

The range must use A1 notation (SheetName!A1:B10). A bare sheet name will fail. Use gog sheets get, not gog sheets read.

Command Groups

Always use full command names (e.g. gog gmail send, not gog send). Always place flags after the full command path (e.g. gog gmail search 'query' --account work, not gog --account work gmail search 'query'). Run gog <group> --help for full subcommand list.

Additional Resources

Reference Files

For detailed command references beyond search/read operations, consult:

• references/gmail.md - Send, drafts, labels, thread modify, batch, filters, settings, tracking, watch
• references/calendar.md - Create, update, delete, respond, freebusy, conflicts, team, focus-time, OOO, working-location
• references/drive.md - Upload, mkdir, move, rename, delete, share, permissions, copy, comments
• references/docs.md - Export (prefer --format md for reading), cat, create, write, insert, find-replace, tabs, comments
• references/slides.md - Create, export, add/replace slides, notes
• references/sheets.md - Read, write, append, clear, format, notes, metadata, create, copy, export
• references/forms.md - Create forms, get form details, list/get responses
• references/contacts.md - Search, list, create, update, delete contacts, directory, other contacts
• references/tasks.md - Task lists, add, update, done, undo, delete, clear
• references/people.md - Profile (me), get user, search, relations
• references/auth-config.md - Auth commands, multi-account, aliases, keyring, service accounts, config, env vars

Converted and distributed by TomeVault — claim your Tome and manage your conversions.