gogcli

What this skill does

# 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:

```bash
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:

```bash
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.

```bash
# 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.

```bash
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

| Flag | Description |
|------|-------------|
| `--account` | Account email or alias |
| `--json` | JSON output |
| `--plain` | TSV output |
| `--results-only` | Drop envelope fields in JSON |
| `--select` | Select fields in JSON output |
| `--dry-run` | Print intended actions, don't execute |
| `--force` | Skip confirmations |
| `--no-input` | Never prompt (CI mode) |
| `--verbose` | Debug logging |

## Discovering Flags

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

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

## Gmail Search

### Search Threads

```bash
gog gmail search 'newer_than:7d'                     # Last 7 days
gog gmail search 'from:[email protected]'             # 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)

```bash
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

```bash
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

```bash
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

```bash
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

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

### List Calendars

```bash
gog calendar calendars
```

## Drive Search

### List Files

```bash
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

```bash
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

```bash
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:

```bash
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

| Group | Description |
|-------|-------------|
| `gmail` | Gmail operations |
| `calendar` | Google Calendar |
| `drive` | Google Drive |
| `docs` | Google Docs |
| `slides` | Google Slides |
| `sheets` | Google Sheets |
| `forms` | Google Forms |
| `contacts` | Google Contacts |
| `tasks` | Google Tasks |
| `people` | Google People |
| `chat` | Google Chat (Workspace only) |
| `appscript` | Google Apps Script |
| `auth` | Auth and credentials |
| `config` | Configuration |

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> --