Google Docs (gws-docs)

PREREQUISITE: Read the gws-shared skill for auth, global flags, and security rules.

Read and write Google Docs using the gws CLI.

gws docs <resource> <method> [flags]

Quick Examples

# Create a new blank document
gws docs documents create \
  --json '{"title": "Meeting Notes — March 2026"}'

# Get document content (returns full JSON including body segments)
gws docs documents get \
  --params '{"documentId": "DOCUMENT_ID"}'

# Append text to a document
gws docs documents batchUpdate \
  --params '{"documentId": "DOCUMENT_ID"}' \
  --json '{
    "requests": [
      {
        "insertText": {
          "location": {"index": 1},
          "text": "New paragraph content here.\n"
        }
      }
    ]
  }'

# Insert a heading
gws docs documents batchUpdate \
  --params '{"documentId": "DOCUMENT_ID"}' \
  --json '{
    "requests": [
      {
        "insertText": {
          "location": {"index": 1},
          "text": "Section Title\n"
        }
      },
      {
        "updateParagraphStyle": {
          "range": {"startIndex": 1, "endIndex": 14},
          "paragraphStyle": {"namedStyleType": "HEADING_1"},
          "fields": "namedStyleType"
        }
      }
    ]
  }'

# Replace placeholder text (template fill-in)
gws docs documents batchUpdate \
  --params '{"documentId": "DOCUMENT_ID"}' \
  --json '{
    "requests": [
      {
        "replaceAllText": {
          "containsText": {"text": "{{CLIENT_NAME}}", "matchCase": false},
          "replaceText": "Acme Corp"
        }
      }
    ]
  }'

# Insert a table
gws docs documents batchUpdate \
  --params '{"documentId": "DOCUMENT_ID"}' \
  --json '{
    "requests": [
      {
        "insertTable": {
          "rows": 3,
          "columns": 3,
          "location": {"index": 1}
        }
      }
    ]
  }'

Helper Commands

Command	Description
gws docs +write	Append text to a document (simplified)

Common batchUpdate Request Types

Request type	What it does
insertText	Insert text at a specific index
deleteContentRange	Remove a range of content
replaceAllText	Find and replace throughout document
insertPageBreak	Insert a page break
updateParagraphStyle	Apply a heading or paragraph style
updateTextStyle	Bold, italic, font, size
insertTable	Insert a table
insertInlineImage	Embed an image
createNamedRange	Mark a range for later reference

Reading Document Content

The documents.get response contains a body.content array of structural elements:

{
  "documentId": "...",
  "title": "My Document",
  "body": {
    "content": [
      { "paragraph": { "elements": [{ "textRun": { "content": "Hello\n" } }] } }
    ]
  }
}

Extract plain text with jq:

gws docs documents get --params '{"documentId": "DOC_ID"}' \
  | jq '[.. | .textRun?.content? // empty] | join("")'

Key API Resources

documents

get, create, batchUpdate

Discovering More

gws docs --help
gws schema docs.documents.batchUpdate
gws schema docs.documents.get