google-docs

name	google-docs
description	Read, view, create, edit, and format Google Docs using the gdocs CLI. Access document content, insert and manipulate text, apply formatting (bold, italic, underline, colors, fonts), manage tables, add images, and export documents. Use when user wants to read, view, see, open, or access a Google Doc, shares a docs.google.com URL, mentions gdocs, or asks to create/modify documents.
allowed-tools	Bash, Read

Google Docs CLI

This skill provides access to Google Docs through the gdocs command-line tool.

Prerequisites Check

Before using gdocs commands, verify the CLI is installed and authenticated:

# Check if gdocs is installed
which gdocs || echo "Not installed - run: npm install -g gdocs-cli"

# Check authentication status
gdocs auth status

If not authenticated, guide the user to SETUP.md.

Shell Escaping

Important: Before running gdocs commands, detect the user's shell to handle escaping correctly:

echo $0   # or: echo $SHELL

Newlines and special characters differ by shell:

• bash/zsh: Use $'...' syntax for literal escape sequences: gdocs text insert DOC_ID $'Line one\nLine two' --at 1
• fish: Use \n directly in double quotes: gdocs text insert DOC_ID "Line one\nLine two" --at 1
• sh/dash: Escape sequences in double quotes are NOT interpreted. Use printf: gdocs text insert DOC_ID "$(printf 'Line one\nLine two')" --at 1

Common pitfalls:

• "Hello\nWorld" in bash/zsh passes the literal characters \n, NOT a newline. You must use $'Hello\nWorld' or "$(printf 'Hello\nWorld')".
• Hex color codes with # should always be quoted: --bg "#4a86c8" (unquoted # starts a comment in most shells).
• When in doubt, use $'...' in bash/zsh or the printf subshell approach, which works everywhere.

Quick Reference

Set Working Document

Set a default document to avoid passing DOC_ID to every command:

gdocs use DOC_ID
# Now all commands use this document by default

Reading a Document

Always start with doc info to understand what's in the document:

gdocs doc info DOC_ID

This shows:

• Character/word count
• Number of tables (with dimensions)
• Number of images
• Headers/footers

Important: If the document has tables, most content may be there rather than in body text. Check doc info first to know whether to use text read or table read.

# If doc info shows tables:
gdocs table list DOC_ID      # See all tables
gdocs table read DOC_ID 0    # Read first table

# If doc info shows body text:
gdocs text read DOC_ID

Document Operations

# Create a new document
gdocs doc create "Document Title"

# Get document content
gdocs doc get DOC_ID

# Open in browser
gdocs doc open DOC_ID

Text Operations

# Insert text at position (1 = beginning)
gdocs text insert DOC_ID "Hello World" --at 1

# Append text to end (use $'...' for newlines in bash/zsh)
gdocs text insert DOC_ID $'\n\nNew paragraph' --end

# Read document text
gdocs text read DOC_ID

# Find text (shows position indexes)
gdocs text find DOC_ID "search term"

# Replace text
gdocs text replace DOC_ID "old" "new" --all

# Delete text range
gdocs text delete DOC_ID --from 10 --to 50

Formatting

# Bold, italic, underline, strikethrough
gdocs format bold DOC_ID --from 1 --to 10
gdocs format italic DOC_ID --from 1 --to 10
gdocs format underline DOC_ID --from 1 --to 10
gdocs format strikethrough DOC_ID --from 1 --to 10

# Remove formatting with --remove flag
gdocs format bold DOC_ID --from 1 --to 10 --remove

# Text color (named or hex)
gdocs format color DOC_ID red --from 1 --to 10
gdocs format color DOC_ID "#ff5500" --from 1 --to 10

# Background/highlight color
gdocs format color DOC_ID yellow --from 1 --to 10 --background

# Font and size
gdocs format font DOC_ID "Roboto Mono" --from 1 --to 50
gdocs format size DOC_ID 14 --from 1 --to 50

# Headings (1-6)
gdocs format heading DOC_ID 1 --from 1 --to 20

# Hyperlinks
gdocs format link DOC_ID "https://example.com" --from 10 --to 25

Tables

# Create table (rows x columns)
gdocs table create DOC_ID 3 4 --at 1

# List tables
gdocs table list DOC_ID

# Read table content
gdocs table read DOC_ID 0

# Set cell content directly
gdocs table set-cell DOC_ID 0 --row 1 --col 2 "Cell content"

# Insert/delete rows and columns
gdocs table insert-row DOC_ID 0 --after 2
gdocs table insert-col DOC_ID 0 --after 1
gdocs table delete-row DOC_ID 0 3
gdocs table delete-col DOC_ID 0 2

# Cell background color (e.g., colored header rows)
gdocs table style DOC_ID 0 --row 0 --bg "#4a86c8"

# Remove cell background
gdocs table style DOC_ID 0 --cell 1,2 --no-bg

# Cell borders (all sides)
gdocs table style DOC_ID 0 --row 0 --border-color black --border-width 1

# Per-side borders
gdocs table style DOC_ID 0 --row 0 --border-bottom "#333333" --border-width 2

# Vertical content alignment in cells
gdocs table style DOC_ID 0 --row 0 --valign middle

# Cell padding
gdocs table style DOC_ID 0 --row 0 --padding 4

# Merge cells (rowspan x colspan starting at row,col)
gdocs table merge DOC_ID 0 --row 0 --col 0 --rows 1 --cols 3

# Unmerge cells
gdocs table unmerge DOC_ID 0 --row 0 --col 0 --rows 1 --cols 3

# Text alignment within cells (start/center/end/justified)
gdocs table align DOC_ID 0 --row 0 --center
gdocs table align DOC_ID 0 --col 2 --end

Images

# Insert image from URL
gdocs image insert DOC_ID "https://example.com/image.png" --at 1

# With specific dimensions
gdocs image insert DOC_ID "https://example.com/logo.png" --at 1 --width 200 --height 100

Document Structure

# Page breaks
gdocs structure page-break DOC_ID --at 100

# Headers and footers
gdocs structure header create DOC_ID
gdocs structure footer create DOC_ID
gdocs structure list DOC_ID

# Section breaks
gdocs structure section-break DOC_ID next-page --at 50

Named Ranges (Templates)

Named ranges let you mark text regions for easy updates:

# Create named range
gdocs range create DOC_ID "customer_name" --from 10 --to 30

# List all ranges
gdocs range list DOC_ID

# Update range content
gdocs range update DOC_ID "customer_name" "John Smith"

# Delete range (not the text)
gdocs range delete DOC_ID "customer_name"

Template workflow:

# 1. Create template with placeholders
gdocs range create DOC_ID "name" --from 10 --to 20
gdocs range create DOC_ID "date" --from 30 --to 40

# 2. Fill in values
gdocs range update DOC_ID "name" "Acme Corp"
gdocs range update DOC_ID "date" "2024-01-15"

Key Concepts

Document Indexes

Google Docs uses 1-based indexing:

• Index 1 = start of document
• Each character occupies one index
• Use gdocs text find to locate positions

Document: "Hello World"
Position:  1 2 3 4 5 6 7 8 9 10 11
Character: H e l l o   W o r l  d

To bold "World": gdocs format bold DOC_ID --from 7 --to 12

Output Formats

Most commands support --format flag:

• text (default): Human-readable
• json: Machine-readable for scripting
• table: Tabular display

Troubleshooting

Text read returns empty but document has content

Content is likely in tables. Documents like spreadsheets, itineraries, or forms often store all content in tables:

gdocs table list DOC_ID      # Check for tables
gdocs table read DOC_ID 0    # Read first table

Need entire document content quickly

Use doc info first, then read the appropriate content type:

gdocs doc info DOC_ID        # See structure breakdown
gdocs text read DOC_ID       # Body text
gdocs table read DOC_ID 0    # Tables (if present)

Can't find text position for formatting

Use text find to locate the exact indexes:

gdocs text find DOC_ID "search term"
# Output shows: Index: 45-50
# Then use those indexes for formatting
gdocs format bold DOC_ID --from 45 --to 50

Full Documentation

• SETUP.md - First-time setup and Google Cloud configuration
• REFERENCE.md - Complete command reference