beam-ai-team/google-docs

Google Docs

Read, write, create, and manage Google Docs via OAuth authentication.

Safety Contract

Before creating, editing, replacing, exporting, or sharing a Google Doc, show the account, document ID/title, operation, content summary, output path when used, and expected side effects. Require explicit user approval in the current turn before mutating Docs or writing files. Reading documents with an approved scope does not require additional approval.

Pre-Flight Check (ALWAYS RUN FIRST)

uv run python skills/integrations/google/google-master/scripts/google_auth.py --check --service docs

Exit codes:

• 0: Ready to use - proceed with user request
• 1: Need to login - run python3 skills/integrations/google/google-master/scripts/google_auth.py --login
• 2: Missing credentials or dependencies - see ../google-master/references/setup-guide.md

---

Quick Reference

Read Document

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py read <document_id>

Create Document

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py create "My Document" --content "Initial content here"

Insert Text

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py insert <document_id> "Text to insert" --index 1

Append Text

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py append <document_id> "Text to append at end"

Find and Replace

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py replace <document_id> "old text" "new text"

Export Document

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py export <document_id> --format pdf --output ./report.pdf

List Documents

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py list --query "report"

Copy Document

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py copy <document_id> "Copy of My Document"

Rename Document

uv run python skills/integrations/google/google-docs/scripts/docs_operations.py rename <document_id> "New Title"

---

Document ID

The document ID is in the URL:

https://docs.google.com/document/d/[DOCUMENT_ID]/edit

---

Common Workflows

Generate Report -> Save to Google Docs

from docs_operations import create_document, append_text

doc = create_document("Weekly Report - Jan 2024")
append_text(doc['document_id'], "Key findings from this week...")
print(f"Report created: {doc['url']}")

Create Document from Template

from docs_operations import copy_document, replace_all_text

new_doc = copy_document(template_id, "Invoice #1234")
replace_all_text(new_doc['document_id'], "{{CLIENT}}", "Acme Corp")
replace_all_text(new_doc['document_id'], "{{AMOUNT}}", "$5,000")

---

Available Operations

| Operation | Function | Description | |-----------|----------|-------------| | Read | read_document() | Get document content | | Info | get_document_info() | Get title, ID, URL | | Create | create_document() | Create new document | | Copy | copy_document() | Duplicate document | | Rename | rename_document() | Change title | | Insert | insert_text() | Insert at position | | Append | append_text() | Add to end | | Replace | replace_all_text() | Find and replace | | Export | export_document() | Export to text/HTML/PDF/DOCX | | List | list_documents() | List accessible docs |

---

Error Handling

See ../google-master/references/error-handling.md for common errors and solutions.

---

Setup

First-time setup: ../google-master/references/setup-guide.md

Quick start:

1. pip install google-auth google-auth-oauthlib google-api-python-client
2. Create OAuth credentials in Google Cloud Console (enable Google Docs API & Drive API, choose "Desktop app")
3. Add to .env file at Beam Next root:

   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_PROJECT_ID=your-project-id
   

4. Run python3 skills/integrations/google/google-master/scripts/google_auth.py --login