gdoc

A token-efficient CLI for AI agents to read, write, and collaborate on Google Docs.

gdoc gives AI coding agents (Claude Code, Cursor, Codex, etc.) a simple command-line interface to Google Docs and Drive. Every command is designed to minimize token usage while providing the context agents need — change detection banners, conflict prevention, structured output modes, and inline comment annotations.

Install

uv tool install git+https://github.com/LucaDeLeo/gdoc.git

Or from a local clone:

git clone https://github.com/LucaDeLeo/gdoc.git
cd gdoc
uv tool install .

Setup

1. Create a project in the Google Cloud Console
2. Enable the Google Drive API and Google Docs API
3. Create OAuth 2.0 credentials (Desktop application type)
4. Download the credentials JSON and place it at ~/.config/gdoc/credentials.json
5. Authenticate:

gdoc auth

This opens a browser for the OAuth flow. Use --no-browser for headless environments (prints a URL to visit manually).

Quick start

# List files in Drive root
gdoc ls

# Search for a document
gdoc find "quarterly report"

# Read a document as markdown
gdoc cat DOC_ID

# Read with byte limit (UTF-8-safe truncation)
gdoc cat --max-bytes 5000 DOC_ID

# Read a specific tab
gdoc cat --tab "Notes" DOC_ID

# Read all tabs
gdoc cat --all-tabs DOC_ID

# List tabs in a document
gdoc tabs DOC_ID

# Read with inline comment annotations
gdoc cat --comments DOC_ID

# Get document metadata
gdoc info DOC_ID

# Find and replace text (supports markdown formatting)
gdoc edit DOC_ID "old text" "**new bold text**"

# Overwrite a document from a local file
gdoc write DOC_ID draft.md

# Create a new blank document
gdoc new "Meeting Notes"

# Create a document from a local markdown file (with image support)
gdoc new "Report" --file report.md

# Duplicate a document
gdoc cp DOC_ID "Copy of Report"

# List images, charts, and drawings
gdoc images DOC_ID

# Download images to a local directory
gdoc images --download /tmp/imgs DOC_ID

All commands accept a full Google Docs URL or a bare document ID:

gdoc cat https://docs.google.com/document/d/1aBcDeFg.../edit
gdoc cat 1aBcDeFg...

Commands

Reading

Writing

Comments

Other

Output modes

Every command supports four output modes:

gdoc info DOC              # terse (default) — compact, human-readable
gdoc info --verbose DOC    # verbose — all fields, full timestamps
gdoc info --json DOC       # json — machine-readable, wrapped in {"ok": true, ...}
gdoc info --plain DOC      # plain — stable TSV, no decoration, suitable for piping

The --json, --verbose, and --plain flags are mutually exclusive and can go before or after the subcommand.

Plain mode produces tab-separated output with no headers or decoration. Action commands emit key\tvalue pairs; list commands emit one row per item with tab-separated fields.

Awareness system

gdoc tracks per-document state to help agents stay aware of external changes. Before most commands, a pre-flight check runs automatically and prints a banner to stderr:

--- first interaction with this doc ---
 📄 "Project Spec" by [email protected], last edited 2026-02-07
 💬 3 open comments, 1 resolved
---

On subsequent interactions:

--- since last interaction (12 min ago) ---
 ✎ doc edited by [email protected] (v4 → v6)
 💬 new comment #abc by [email protected]: "Should we add error handling here?"
 ✓ comment #def resolved by [email protected]
---

If nothing changed: --- no changes ---

Conflict prevention

The write command blocks if the document was modified since your last read:

gdoc cat DOC               # establishes a read baseline
# ... someone else edits the doc ...
gdoc write DOC draft.md    # ERR: doc changed since last read
gdoc cat DOC               # re-read to update baseline
gdoc write DOC draft.md    # OK written

Use --force to skip conflict detection. Use --quiet to skip pre-flight checks entirely (saves 2 API calls).

Annotated view

cat --comments produces line-numbered output with comments placed inline next to the text they reference:

     1	# Project Spec
     2
     3	The system should handle up to 1000 concurrent users.
      	  [#abc open] [email protected] on "up to 1000 concurrent users":
      	    "Is this enough? We had 1500 at peak last month."
      	    > [email protected]: "Good point, let's bump to 2000."
     4
     5	Authentication uses OAuth2.

Comments whose anchor text has been deleted, is too short, or is ambiguous are grouped in an [UNANCHORED] section at the end.

Tabs

Google Docs supports multiple tabs per document. The default cat command uses Drive export which only returns the first tab. Use --tab or --all-tabs to read tab content via the Docs API:

# List tabs in a document
gdoc tabs DOC
# t.0	Tab 1
# t.abc	Notes

# Read a specific tab by title (case-insensitive) or ID
gdoc cat --tab "Notes" DOC

# Read all tabs with headers
gdoc cat --all-tabs DOC
# === Tab: Tab 1 ===
# ...content...
# === Tab: Notes ===
# ...content...

--tab and --all-tabs are mutually exclusive with --comments. They work with --json and --plain.

Byte truncation

Use --max-bytes on cat to limit output size. Truncation is UTF-8-safe (never splits a multi-byte character):

gdoc cat --max-bytes 5000 DOC   # first ~5KB of content

Works with all cat modes: default, --tab, --all-tabs, --comments. In --json mode, truncation applies to the content field, not the JSON envelope.

Native table insertion

edit supports markdown tables in replacement text. Tables are inserted as native Google Docs tables:

gdoc edit DOC "placeholder" "| Name | Score |
|------|-------|
| Alice | 95 |
| Bob | 87 |"

Tables require a single match — use without --all when the replacement contains a table.

Import from file

Create a document from a local markdown file with new --file:

gdoc new "Report" --file report.md

Images in the markdown are handled automatically:

• Remote images (https://...) are inserted directly via URL
• Local images are uploaded to Drive temporarily, inserted, then cleaned up
• Supported formats: PNG, JPG, JPEG, GIF, WebP

Image inspection

List and download images, charts, and drawings embedded in a document:

# List all images with metadata
gdoc images DOC
# kix.abc  image  "Company Logo"  200x100pt
# kix.def  chart  "Q1 Revenue"    400x300pt
# kix.ghi  drawing  (not exportable)  150x150pt

# Download images to a local directory
gdoc images --download /tmp/imgs DOC
# /tmp/imgs/kix.abc.png
# /tmp/imgs/kix.def.png
# WARN: kix.ghi is a drawing (cannot export)

# Download a specific image by object ID
gdoc images --download /tmp/imgs DOC kix.abc

Drawings cannot be exported (the Google API exposes no content for them). Charts are rendered as images via their content URI. Downloaded files can be viewed directly by multimodal AI agents.

Command allowlist

Restrict which subcommands are available using --allow-commands or the GDOC_ALLOW_COMMANDS environment variable. Useful for sandboxing AI agents to read-only operations:

# Only allow read commands
gdoc --allow-commands cat,ls,find,info,comments cat DOC

# Via environment variable
export GDOC_ALLOW_COMMANDS=cat,ls,find,info,comments
gdoc edit DOC "old" "new"  # ERR: command not allowed: edit

Exit codes

Errors always print ERR: <message> to stderr, even in --json mode.

Configuration

All files are stored under ~/.config/gdoc/:

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Run a single test
uv run pytest tests/test_cat.py -k "test_name" -v

# Lint
uv run ruff check gdoc/ tests/

Changelog

Release notes and upgrade highlights live in CHANGELOG.md.

License

MIT