google-docs

Files (8)

• SKILL.md
• gauth.py · scripts/
• gcalendar.py · scripts/
• gdocs.py · scripts/
• gdrive.py · scripts/
• gmail.py · scripts/
• gsheets.py · scripts/
• gslides.py · scripts/

SKILL.md (first lines)

# Google Workspace Integration

Portable Python scripts for Google Workspace APIs. No SDK-specific code — works with any agent that can run shell commands.

## Prerequisites

- `gcloud` CLI installed and authenticated
- `uv` (Python package runner): `curl -LsSf https://astral.sh/uv/install.sh | sh`

## Quick Start

```bash
# Run any script directly — uv handles dependencies automatically
uv run scripts/gdocs.py read <DOCUMENT_ID>
uv run scripts/gsheets.py read <SPREADSHEET_ID>
uv run scripts/gdrive.py search "quarterly report"
uv run scripts/gmail.py list --max-results 5
uv run scripts/gcalendar.py list-events
uv run scripts/gslides.py read <PRESENTATION_ID>
```

All scripts output JSON to stdout, diagnostics to stderr.

## Authentication

Scripts use `gcloud auth application-default` credentials with a quota project header. Auth is automatic — scripts get tokens via `gcloud auth application-default print-access-token` and auto-detect the quota project from `~/.config/gcloud/application_default_credentials.json`.

### First-Time Setup

```bash
PROJECT="ck-orp-nick-dev"  # or your GCP project with Workspace APIs enabled

# 1. Enable APIs
gcloud services enable \
  docs.googleapis.com slides.googleapis.com drive.googleapis.com \
  sheets.googleapis.com calendar-json.googleapis.com gmail.googleapis.com \
  --project=$PROJECT

# 2. Authenticate with all scopes (sets quota project automatically)
gcloud auth application-default login \
  --billing-project=$PROJECT \
  --scopes="\
https://www.googleapis.com/auth/cloud-platform,\
https://www.googleapis.com/auth/documents,\
https://www.googleapis.com/auth/presentations,\
https://www.googleapis.com/auth/drive,\
https://www.googleapis.com/auth/drive.file,\
https://www.googleapis.com/auth/spreadsheets,\
https://www.googleapis.com/auth/calendar,\
https://www.googleapis.com/auth/calendar.events,\
https://www.googleapis.com/auth/gmail.modify,\
https://www.googleapis.com/auth/gmail.readonly,\
https://www.googleapis.com/auth/gmail.send,\
https://www.googleapis.com/auth/gmail.labels,\
https://www.googleapis.com/auth/tasks,\
https://www.googleapis.com/auth/userinfo.email,\
https://www.googleapis.com/auth/userinfo.profile"
```

### Auth Helper

```bash
uv run scripts/gauth.py token           # Print access token
uv run scripts/gauth.py quota-project   # Print current quota project
uv run scripts/gauth.py setup-info      # Print full setup instructions as JSON
```

## Scripts Reference

### `scripts/gdocs.py` — Google Docs

```bash
# Reading
uv run scripts/gdocs.py read <DOC_ID>
uv run scripts/gdocs.py get-structure <DOC_ID>

# Creating & editing
uv run scripts/gdocs.py create --title "My Doc" --content "Hello world"
uv run scripts/gdocs.py append <DOC_ID> --text "New paragraph"
uv run scripts/gdocs.py find-replace <DOC_ID> --find "old" --replace "new" [--match-case]
uv run scripts/gdocs.py clear-document <DOC_ID>

# Formatting
uv run scripts/gdocs.py format-document <DOC_ID>                    # Auto-style entire doc
uv run scripts/gdocs.py apply-heading-style <DOC_ID> --find-text "Title" --level 1
uv run scripts/gdocs.py format-text <DOC_ID> --find-text "important" --bold --foreground-color "#FF0000"
uv run scripts/gdocs.py link-text <DOC_ID> --find-text "click here" --url "https://example.com"
uv run scripts/gdocs.py insert-heading <DOC_ID> --text "New Section" --level 2 [--index 42]

# Batch formatting (JSON operations array)
uv run scripts/gdocs.py batch-format <DOC_ID> --operations '[{"type":"heading","startIndex":2,"endIndex":50,"level":1}]'

# Formatted sections (JSON content blocks)
uv run scripts/gdocs.py write-formatted-section <DOC_ID> --content '[
  {"type":"h1","text":"Section Title"},
  {"type":"text","text":"Body paragraph."},
  {"type":"bullet","text":"First point"},
  {"type":"code","text":"example_code()"}
]'

# Tables
uv run scripts/gdocs.py insert-table <DOC_ID> --rows 3 --columns 2 --data '[["H1","H2"],["a","b"],["c","d"]]'
uv run scripts/gdocs.py insert-styled-table <DOC_ID> --headers "Name,Type,Desc" \
  --rows '[["INT64","Number","Primary key"],["STRING","Text","Labels"]]'
```

**format-text flags:** `--bold/--no-bold`, `--italic/--no-italic`, `--underline/--no-underline`, `--font-size N`, `--foreground-color "#HEX"`, `--background-color "#HEX"`

**write-formatted-section block types:** `title`, `h1`, `h2`, `h3`, `h4`, `text`, `bullet`, `code`. Text blocks accept `"bold": true`.

**Styling:** `format-document` applies professional styling (Google Sans Text font, red headings for H1/H2, dark headers for H3+, proper spacing). Tables get dark `#333333` header rows with white text and `#F9F9F9` alternating rows.

### `scripts/gsheets.py` — Google Sheets

```bash
uv run scripts/gsheets.py read <SHEET_ID> [--range "Sheet1!A1:D10"]
uv run scripts/gsheets.py get-info <SHEET_ID>
uv run scripts/gsheets.py create --title "New Sheet" [--sheet-names '["Data","Summary"]']
uv run scripts/gsheets.py write <SHEET_ID> --range "A1" --values '[["Name","Age"],["Alice","30"]]'

From djmittens/neo-mittens, MIT.

More from djmittens/neo-mittens