GitHub - famasya/gdocs-cli: A command-line tool to fetch Google Docs content and convert it to Markdown with YAML frontmatter.

A command-line tool to fetch Google Docs content and convert it to Markdown with YAML frontmatter.

Designed for AI Coding Agents: This tool is specifically built to help AI coding agents fetch Google Docs documentation and convert it to clean markdown for analysis, context gathering, or integration into AI workflows. The stdout-based output and --clean flag make it ideal for piping into AI systems.

📖 See AGENTS.md for a comprehensive guide on integrating this tool with AI coding agents (Claude Code, Aider, Cursor, MCP servers, etc.).

Features

OAuth2 authentication with automatic token caching
Converts Google Docs to clean Markdown format
YAML frontmatter with document metadata
Supports text formatting: bold, italic, strikethrough, links
Supports document structure: headings, lists (bullet and numbered), tables
Output to stdout for easy piping to files or other commands

Prerequisites

Go 1.24.1 or later
A Google Cloud project with Google Docs API enabled
OAuth 2.0 credentials (Desktop application type)

Installation

From Release Binaries

Prebuilt binaries for Linux, macOS, and Windows are available on the GitHub Releases page.

# Download and install the latest release for your platform
# Linux (amd64)
curl -L https://github.com/famasya/gdocs-cli/releases/latest/download/gdocs-cli-linux-amd64 -o gdocs-cli
chmod +x gdocs-cli

# macOS (Apple Silicon)
curl -L https://github.com/famasya/gdocs-cli/releases/latest/download/gdocs-cli-darwin-arm64 -o gdocs-cli
chmod +x gdocs-cli

# macOS (Intel)
curl -L https://github.com/famasya/gdocs-cli/releases/latest/download/gdocs-cli-darwin-amd64 -o gdocs-cli
chmod +x gdocs-cli

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/famasya/gdocs-cli/releases/latest/download/gdocs-cli-windows-amd64.exe" -OutFile "gdocs-cli.exe"

From Source

git clone https://github.com/famasya/gdocs-cli.git
cd gdocs-cli
go build -o gdocs-cli cmd/gdocs-cli/main.go

Using Go Install

go install github.com/famasya/gdocs-cli/cmd/gdocs-cli@latest

Google Cloud Setup

Before using this tool, you need to set up OAuth2 credentials:

1. Create a Google Cloud Project

Go to Google Cloud Console
Create a new project or select an existing one
Navigate to "APIs & Services" > "Library"
Search for "Google Docs API" and enable it

2. Create OAuth 2.0 Credentials

Go to "APIs & Services" > "Credentials"
Click "Create Credentials" > "OAuth client ID"
If prompted, configure the OAuth consent screen:
- Choose "External" user type
- Fill in required fields (app name, user support email)
- Add your email as a test user
- Save and continue
Choose "Desktop application" as the application type
Give it a name (e.g., "gdocs-cli")
Click "Create"
Download the credentials JSON file
Save it as credentials.json (or any name you prefer)

Important: Keep this file secure and never commit it to version control.

Usage

Initialize Authentication (Recommended First Step)

Before using the CLI for the first time, set up your credentials and initialize OAuth authentication:

Option 1: Use default config location (recommended for AI agents)

# Copy your credentials to the default location
mkdir -p ~/.config/gdocs-cli
cp credentials.json ~/.config/gdocs-cli/config.json

# Initialize OAuth (will use default config automatically)
./gdocs-cli --init

Option 2: Specify config path

./gdocs-cli --init --config="./credentials.json"

This will:

Open your browser for Google OAuth consent
Ask you to authorize the application
Save the token to ~/.config/gdocs-cli/token.json

After initialization, you can use the CLI without re-authenticating.

Basic Usage

Using default config location:

./gdocs-cli --url="https://docs.google.com/document/d/YOUR_DOC_ID/edit"

Specifying config path:

./gdocs-cli --url="https://docs.google.com/document/d/YOUR_DOC_ID/edit" --config="./credentials.json"

The tool will automatically use the cached token - no browser interaction needed.

Note: If --config is not provided, the tool looks for credentials at ~/.config/gdocs-cli/config.json by default. This makes it easy for AI agents to use the tool without specifying the config path every time.

Output to File

./gdocs-cli --url="https://docs.google.com/document/d/YOUR_DOC_ID/edit" > output.md

Piping to Other Commands

./gdocs-cli --url="..." | less
./gdocs-cli --url="..." | grep "keyword"

Include Comments

Use the --comments flag to include document comments in the markdown output:

./gdocs-cli --url="https://docs.google.com/document/d/YOUR_DOC_ID/edit" --comments

This appends a ## Comments section at the end of the markdown with quoted text, author, date, and replies.

⚠️ Important: The --comments flag requires the https://www.googleapis.com/auth/drive.readonly scope. If you previously authenticated without this scope, you need to delete your cached token and re-authenticate:
rm ~/.config/gdocs-cli/token.json
./gdocs-cli --init
Also make sure you don't have non-HTTPS redirect URIs in any of your Google OAuth clients, as Google requires HTTPS for the Drive API scope.

Clean Output (Suppress Logs)

Use the --clean flag to suppress all log output and only show the markdown:

./gdocs-cli --url="..." --clean

This is useful when:

Piping output to AI systems or other tools
Saving to a file without log messages
Using in scripts where only the markdown is needed

Example:

# Without --clean: shows logs like "Fetching document..." to stderr
./gdocs-cli --url="..." > output.md

# With --clean: only markdown to stdout, no logs
./gdocs-cli --url="..." --clean > output.md

# Perfect for AI agents: clean output piped to processing
./gdocs-cli --url="..." --clean | your-ai-tool

Print Integration Instructions

Use the --instruction flag to print instructions for integrating this tool with AI coding agents:

./gdocs-cli --instruction

Quick Integration: Add this one-liner to your project's AGENTS.md, CLAUDE.md, or MCP config:

This project uses gdocs-cli. Run `gdocs-cli --instruction` for usage.

Supported Google Docs Features

Text Formatting

Bold text
Italic text
Bold and italic
~~Strikethrough~~
Links

Document Structure

Headings (H1 through H6)
Bullet lists
Numbered lists
Nested lists
Paragraphs
Tables

YAML Frontmatter

The tool adds YAML frontmatter with document metadata:

---
title: Document Title
author: (if available)
created: (if available)
modified: (if available)
---

Note: The Google Docs API v1 doesn't provide author or date information for the document. These fields may be empty in the frontmatter unless fetched from Google Drive API. Comments are supported via --comments flag (see below).

Known Limitations

Tables: Complex tables with merged cells may not convert perfectly to Markdown
Images: Inline images are not currently supported
Drawings: Not supported - will be skipped
Equations: Not supported - will be skipped
Comments: Supported via --comments flag (requires Drive API scope, see below)
Metadata: Author and dates in frontmatter are not yet extracted (comments via Drive API are supported)

Troubleshooting

Error: Failed to read credentials file

Cause: The credentials file path is incorrect or the file doesn't exist.

Solution:

Verify the file path in the --config flag
Ensure you've downloaded the OAuth credentials JSON from Google Cloud Console
Use an absolute path or relative path from your current directory

Error: Unable to access document

Possible causes:

The document is private and you don't have permission
The document doesn't exist
The document ID is incorrect

Solutions:

Ensure the document is shared with your Google account
Verify you're authenticated with the correct Google account
Check that the URL is correct
Try opening the document in your browser first

Browser doesn't open during OAuth

Solution: The authorization URL will be printed in the terminal. Copy and paste it into your browser manually.

Token expired or invalid

Solution: Delete the cached token and re-authenticate using the --init flag:

rm ~/.config/gdocs-cli/token.json
./gdocs-cli --init --config="credentials.json"

Permission denied when creating config directory

Solution: Ensure you have write permissions to ~/.config/. Try creating it manually:

mkdir -p ~/.config/gdocs-cli
chmod 700 ~/.config/gdocs-cli

Development

Project Structure

gdocs-cli/
├── cmd/gdocs-cli/main.go              # CLI entry point
├── internal/
│   ├── auth/
│   │   ├── oauth.go                   # OAuth2 flow implementation
│   │   └── token.go                   # Token caching
│   ├── gdocs/
│   │   ├── client.go                  # Docs API client
│   │   └── url.go                     # URL parsing
│   └── markdown/
│       ├── converter.go               # Main converter
│       ├── text.go                    # Text formatting
│       ├── structure.go               # Structure conversion
│       └── frontmatter.go             # YAML frontmatter
├── go.mod
├── go.sum
└── README.md

Building from Source

go build -o gdocs-cli cmd/gdocs-cli/main.go

Running Tests

The project includes comprehensive unit tests for all core functionality:

# Run all tests
go test ./...

# Run tests with verbose output
go test ./... -v

# Run tests for a specific package
go test ./internal/gdocs -v
go test ./internal/markdown -v
go test ./internal/auth -v

Test Coverage:

CLI Integration (cmd/gdocs-cli/main_test.go): End-to-end tests for CLI flags, error handling, and user flows
- Help flag functionality
- Missing required flags validation
- Invalid URL handling
- Missing credentials file errors
- Clean flag recognition
URL Parsing (internal/gdocs/url_test.go): Tests for extracting document IDs from various URL formats
Text Formatting (internal/markdown/text_test.go): Tests for bold, italic, links, and text style conversion
Structure Conversion (internal/markdown/structure_test.go): Tests for headings, lists, tables, and paragraph conversion
Token Handling (internal/auth/token_test.go): Tests for token saving, loading, and file permissions

Total: 45+ test cases covering both unit and integration testing. All tests pass successfully and ensure the reliability of the CLI tool.

Security Considerations

Credentials file: Never commit your credentials.json to version control
Token cache: Tokens are stored in ~/.config/gdocs-cli/token.json with 0600 permissions (read/write for owner only)
OAuth scope: The tool requests documents.readonly and drive.readonly scopes - no write access
Config directory: Created with 0700 permissions (accessible only by owner)

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

Built with: