Smart GWS Docs Write

Create, edit, and format Google Docs content programmatically from the command line.

When to Use This Command

Run this command when you need to:

• Generate or update Google Docs content from templates, data sources, or automated pipelines
• Apply bulk formatting changes like heading styles, font updates, or table insertion across documents
• Merge data from spreadsheets or databases into document templates for reports and correspondence

Consider alternatives when:

• You need real-time collaborative editing with visual formatting using the Docs web interface
• You are performing simple one-time edits where opening the document directly is faster

Quick Start

Configuration

Copy
name: smart-gws-docs-write
type: command
category: google-workspace

Example Invocation

Copy
claude command:run smart-gws-docs-write --doc-id "1BxiMVs0X" --action insert --content "## Q1 Summary\nRevenue grew 23% year-over-year."

Example Output

Connecting to Google Docs...
  Document: Q1 Business Review (1BxiMVs0X)
  Owner: [email protected]
  Last modified: 2026-03-14

Inserting content...
  Position: end of document
  Content type: markdown (converted to Docs formatting)

Changes applied:
  + Heading 2: "Q1 Summary"
  + Paragraph: "Revenue grew 23% year-over-year."

Document updated successfully.
  URL: https://docs.google.com/document/d/1BxiMVs0X/edit
  Revision: 14

Core Concepts

Docs Write Operations Overview

Aspect	Details
Insert	Add text, headings, tables, images, or page breaks at specified positions
Replace	Find and replace text patterns or merge template placeholders with data
Format	Apply styles: fonts, sizes, colors, bold, italic, alignment, spacing
Structure	Manage headers, footers, sections, table of contents, and page setup
Templates	Fill document templates with data from JSON, CSV, or spreadsheet sources

Document Update Workflow

Open Document by ID
        |
        v
Read Current Content
  (for position reference)
        |
        v
Apply Operations
  |       |        |
  v       v        v
Insert  Replace  Format
  |       |        |
  v       v        v
Commit Batch Request
        |
        v
Verify Changes
        |
        v
Return Updated URL

Configuration

Parameter	Type	Default	Description
doc-id	string	(required)	Google Docs document ID from the document URL
action	string	(required)	Operation: insert, replace, format, template
content	string	(none)	Content to insert or template data as JSON
position	string	end	Insert position: start, end, or character index
template-data	string	(none)	Path to JSON or CSV file for template merge

Best Practices

1. Use batch operations - The Docs API supports batching multiple operations in a single request. Combine related inserts and formatting changes to reduce API calls and improve performance.

2. Reference positions carefully - Document positions use character indices that shift as content is added. Process insertions from the end of the document backward to maintain correct indices.

3. Convert markdown to Docs format - The command supports markdown input that gets converted to proper Docs formatting. This is easier than specifying Docs API formatting objects manually.

4. Template with placeholders - Use double-brace placeholders like {{company_name}} in your document templates. The template action replaces all occurrences with provided data values.

Common Issues

1. Document not found - Verify the document ID is correct. The ID is the long string in the document URL between /d/ and /edit. Shared documents may require explicit viewer or editor access.

2. Formatting lost on insert - Plain text inserts do not carry formatting. Use the format action after inserting content to apply styles, or use markdown input for automatic conversion.

3. Template placeholders not replaced - Ensure placeholder syntax matches exactly, including double braces and case sensitivity. Run a dry-run first to verify which placeholders the command detects.