Gcmd

Google Drive CLI (gcmd) Skill

Quick reference for using gcmd CLI tool to work with Google Drive files.

Repository: /Users/ben/git/gcmd

Overview

gcmd is a Python CLI tool for working with Google Drive from the command line. Useful for:

• Exporting Google Docs as markdown for processing/archival
• Listing and searching Drive files
• Downloading files
• Viewing file metadata, permissions, and comments
• Reviewing document feedback and collaboration

When to Use This Skill

Use this skill when:

• User asks to export Google Docs as markdown
• User provides a Google Drive URL and wants to read/access the content
• User asks to search for files in Google Drive
• User wants to view file permissions or comments on Google Docs
• User mentions "meeting notes" or "Gemini notes" from Google Meet
• User asks to list recent Google Drive files

Common Commands

All commands must be run from the gcmd directory with uv run gcmd.

Export Google Docs as Markdown

RECOMMENDED: Export to /tmp/ for easy reading by Claude Code

cd /Users/ben/git/gcmd
uv run gcmd export "https://docs.google.com/document/d/FILE_ID/edit" -o /tmp/
# Creates: /tmp/Document Title.md (uses document title as filename)

Export to specific file path:

uv run gcmd export FILE_ID -o /tmp/meeting-notes.md
# Creates: /tmp/meeting-notes.md

Export all tabs as separate files:

uv run gcmd export --all-tabs FILE_ID -o /tmp/
# Creates: /tmp/Document Title - Tab1.md, /tmp/Document Title - Tab2.md, etc.

How -o works:

• Without -o: Saves to /Users/ben/git/gcmd/ using document title + .exported.md
• With -o /tmp/ (directory): Saves to /tmp/ using document title + .md extension (no .exported)
• With -o /tmp/file.md (file): Saves to exact path /tmp/file.md

After exporting, ALWAYS read the file to provide the user with the content.

List and Search Files

cd /Users/ben/git/gcmd

# List recent files (default 20, sorted by modified date)
uv run gcmd list

# Search for files by name or content
uv run gcmd list -q "quarterly report"

# List only Google Docs
uv run gcmd list -t docs

# List with verbose details
uv run gcmd list -v -n 10

# List only folders
uv run gcmd list -t folders

# List Google Sheets
uv run gcmd list -t sheets

View File Info

cd /Users/ben/git/gcmd

# Basic file metadata
uv run gcmd info "https://docs.google.com/document/d/FILE_ID/edit"

# Detailed info with permissions, tabs, structure, and comments
uv run gcmd info -v "https://docs.google.com/document/d/FILE_ID/edit"

# Show only comments (without other verbose details)
uv run gcmd info --show-comments "https://docs.google.com/document/d/FILE_ID/edit"

# Also works with just file ID
uv run gcmd info FILE_ID -v

Detailed info shows:

• File metadata (name, type, size, dates)
• Owner and last modifier
• All permissions (users, groups, domains, public links)
• Your capabilities (can edit, comment, share, download, etc.)
• Document tabs (for multi-tab Google Docs)
• Document outline with all headings
• Comments and replies with quoted text, authors, timestamps, and status (resolved/deleted)

Download Files

cd /Users/ben/git/gcmd

# Download to current directory
uv run gcmd download FILE_ID

# Download to specific path
uv run gcmd download FILE_ID -o ~/Downloads/myfile.pdf

# Works with URLs
uv run gcmd download "https://drive.google.com/file/d/FILE_ID/view"

URL Format Support

All commands accept multiple URL formats:

# Google Docs
https://docs.google.com/document/d/FILE_ID/edit
https://docs.google.com/document/d/FILE_ID/edit?tab=t.0

# Google Sheets
https://docs.google.com/spreadsheets/d/FILE_ID/edit

# Google Slides
https://docs.google.com/presentation/d/FILE_ID/edit

# Drive files
https://drive.google.com/file/d/FILE_ID/view

# Just the file ID
FILE_ID

Workflow Example

When user provides a Google Drive URL:

1. Export the document to /tmp/:

   cd /Users/ben/git/gcmd
   uv run gcmd export "URL" -o /tmp/
   

2. Read the exported file: The file will be in /tmp/ with the document title as filename.

3. Provide the content to the user or answer their questions about it.

4. Optional cleanup: After helping the user, you can delete the exported file:

   rm /tmp/exported-filename.md
   

Common Workflow Examples

Find and export a document

cd /Users/ben/git/gcmd

# Search for the document
uv run gcmd list -q "MCP Server Analysis" -t docs

# Get detailed info (tabs, structure)
uv run gcmd info -v "https://docs.google.com/document/d/FILE_ID/edit"

# Export all tabs to /tmp/ for easy reading
uv run gcmd export --all-tabs FILE_ID -o /tmp/

Check permissions on shared docs

cd /Users/ben/git/gcmd

# View detailed permissions
uv run gcmd info -v FILE_ID

# Shows:
# - Who has access (users, groups, domains, public)
# - Permission levels (owner, writer, reader, commenter)
# - Your capabilities (can edit, share, download, etc.)

Review document feedback

cd /Users/ben/git/gcmd

# View all comments and replies on a document
uv run gcmd info --show-comments "https://docs.google.com/document/d/FILE_ID/edit"

# Shows:
# - All comments with quoted/highlighted text
# - Authors and timestamps
# - Replies with their authors
# - Status (resolved, deleted)
# - Total comment count

List recent work documents

cd /Users/ben/git/gcmd

# List recent Google Docs with details
uv run gcmd list -t docs -v -n 20

Key Features

• URL support: All commands accept full Google Drive URLs or file IDs
• Native markdown export: Preserves formatting (headings, tables, links, bold, italic)
• Multi-tab documents: Use --all-tabs to export each tab separately
• Detailed info: View permissions, sharing, capabilities, document structure
• Comments access: View all comments and replies with quoted text, authors, and timestamps
• Auto-naming: Exported files use .exported.md extension (auto-ignored by git) when no -o specified

Authentication

• Credentials location: ~/.config/gcmd/credentials.json
• Token location: ~/.config/gcmd/token.json

If authentication fails, delete token and re-authenticate:

rm ~/.config/gcmd/token.json
cd /Users/ben/git/gcmd
uv run gcmd list  # Will trigger new auth flow

Important Notes

1. Always use /tmp/ for exports - Makes files easy to find and read
2. Always run from gcmd directory - Commands require cd /Users/ben/git/gcmd
3. Use uv run gcmd - Not just gcmd
4. Read exported files - After exporting, read the file and provide content to user
5. Clean up after - Delete exported files from /tmp/ when done

Troubleshooting

"credentials.json not found": Follow setup steps to create OAuth credentials (see gcmd README)

"Authentication failed": Delete token and re-authenticate:

rm ~/.config/gcmd/token.json
cd /Users/ben/git/gcmd
uv run gcmd list

"Not a Google Doc": Use download command instead of export for non-Doc files

Browser won't open: The CLI will provide a manual URL to paste in your browser

Tips

1. Running commands: Always use uv run gcmd from the gcmd directory
2. Export location: Always use -o /tmp/ when exporting so files are in a predictable location for easy reading
3. File naming: Without -o, exported files use .exported.md extension (auto-ignored by git). With -o /dir/, uses .md
4. Multi-tab documents: Use --all-tabs to export each tab as a separate file
5. Verbose mode: Use -v for detailed information (permissions, structure, comments, etc.)
6. Comments: Use --show-comments to view just comments without other verbose details
7. Search: The -q flag searches both file names and content