gws-docs

What this skill does

# Google Docs (gws docs)

`gws docs` provides CLI access to Google Docs with structured JSON output.

> **Disclaimer:** `gws` is not the official Google CLI. This is an independent, open-source project not endorsed by or affiliated with Google.

## Dependency Check

**Before executing any `gws` command**, verify the CLI is installed:
```bash
gws version
```

If not found, install: `go install github.com/omriariav/workspace-cli/cmd/gws@latest`

## Authentication

Requires OAuth2 credentials. Run `gws auth status` to check.
If not authenticated: `gws auth login` (opens browser for OAuth consent).
For initial setup, see the `gws-auth` skill.

## Quick Command Reference

| Task | Command |
|------|---------|
| Read a document | `gws docs read <doc-id>` |
| Read with formatting | `gws docs read <doc-id> --include-formatting` |
| Get document info | `gws docs info <doc-id>` |
| Create a document | `gws docs create --title "My Doc"` |
| Create with markdown | `gws docs create --title "My Doc" --text "# Heading\n\n**Bold**"` |
| Create with plain text | `gws docs create --title "My Doc" --text "Plain" --content-format plaintext` |
| Append text | `gws docs append <doc-id> --text "New paragraph"` |
| Insert text at position | `gws docs insert <doc-id> --text "Hello" --at 1` |
| Find and replace | `gws docs replace <doc-id> --find "old" --replace "new"` |
| Replace all content | `gws docs replace-content <doc-id> --text "# New content"` |
| Replace from file | `gws docs replace-content <doc-id> --file ./content.md` |
| Delete content | `gws docs delete <doc-id> --from 5 --to 10` |
| Add a table | `gws docs add-table <doc-id> --rows 3 --cols 4` |
| Format text | `gws docs format <doc-id> --from 1 --to 10 --bold` |
| Set paragraph style | `gws docs set-paragraph-style <doc-id> --from 1 --to 100 --alignment CENTER` |
| Set heading style | `gws docs set-paragraph-style <doc-id> --from 1 --to 100 --style HEADING_1` |
| Add a list | `gws docs add-list <doc-id> --at 1 --type bullet --items "A;B;C"` |
| Remove list | `gws docs remove-list <doc-id> --from 1 --to 50` |
| Trash document | `gws docs trash <doc-id>` |
| Permanently delete | `gws docs trash <doc-id> --permanent` |
| Add a tab | `gws docs add-tab <doc-id> --title "Tab 2"` |
| Delete a tab | `gws docs delete-tab <doc-id> --tab-id <id>` |
| Rename a tab | `gws docs rename-tab <doc-id> --tab-id <id> --title "New Name"` |
| Read specific tab | `gws docs read <doc-id> --tab "Tab 2"` |
| Add an image | `gws docs add-image <doc-id> --uri <url>` |
| Insert table row | `gws docs insert-table-row <doc-id> --table-start 5 --row 0 --col 0` |
| Delete table row | `gws docs delete-table-row <doc-id> --table-start 5 --row 0 --col 0` |
| Insert table column | `gws docs insert-table-col <doc-id> --table-start 5 --row 0 --col 0` |
| Delete table column | `gws docs delete-table-col <doc-id> --table-start 5 --row 0 --col 0` |
| Merge table cells | `gws docs merge-cells <doc-id> --table-start 5 --row 0 --col 0 --row-span 2 --col-span 2` |
| Unmerge table cells | `gws docs unmerge-cells <doc-id> --table-start 5 --row 0 --col 0 --row-span 2 --col-span 2` |
| Pin header rows | `gws docs pin-rows <doc-id> --table-start 5 --count 1` |
| Insert page break | `gws docs page-break <doc-id> --at 10` |
| Insert section break | `gws docs section-break <doc-id> --at 10` |
| Add header | `gws docs add-header <doc-id>` |
| Delete header | `gws docs delete-header <doc-id> <header-id>` |
| Add footer | `gws docs add-footer <doc-id>` |
| Delete footer | `gws docs delete-footer <doc-id> <footer-id>` |
| Add named range | `gws docs add-named-range <doc-id> --name "range1" --from 1 --to 10` |
| Delete named range | `gws docs delete-named-range <doc-id> --name "range1"` |
| Add footnote | `gws docs add-footnote <doc-id> --at 5` |
| Delete object | `gws docs delete-object <doc-id> <object-id>` |
| Replace image | `gws docs replace-image <doc-id> --object-id <id> --uri <url>` |
| Replace named range | `gws docs replace-named-range <doc-id> --name "range1" --text "new"` |
| Update doc margins | `gws docs update-style <doc-id> --margin-top 72` |
| Update section style | `gws docs update-section-style <doc-id> --from 1 --to 100 --column-count 2` |
| Update cell style | `gws docs update-table-cell-style <doc-id> --table-start 5 --row 0 --col 0 --bg-color "#FF0000"` |
| Update column width | `gws docs update-table-col-properties <doc-id> --table-start 5 --col-index 0 --width 200` |
| Update row height | `gws docs update-table-row-style <doc-id> --table-start 5 --row 0 --min-height 50` |

## Detailed Usage

### read — Read document content

```bash
gws docs read <document-id> [flags]
```

**Flags:**
- `--include-formatting` — Include formatting information and element positions

Use `--include-formatting` to see position indices needed for `insert`, `delete`, and `add-table`.

### info — Get document info

```bash
gws docs info <document-id>
```

Gets metadata about a Google Doc (title, ID, revision info).

### create — Create a new document

```bash
gws docs create --title <title> [flags]
```

**Flags:**
- `--title string` — Document title (required)
- `--text string` — Initial text content
- `--content-format string` — Content format: `markdown` (default), `plaintext`, or `richformat`

**Examples:**
```bash
gws docs create --title "Meeting Notes"
gws docs create --title "Report" --text "# Q4 Summary\n\n**Revenue** grew 15%"
gws docs create --title "Plain" --text "No formatting" --content-format plaintext
```

### append — Append text

```bash
gws docs append <document-id> --text <text> [flags]
```

**Flags:**
- `--text string` — Text to append (required)
- `--newline` — Add newline before appending (default: true)
- `--content-format string` — Content format: `markdown` (default), `plaintext`, or `richformat`

### insert — Insert text at position

```bash
gws docs insert <document-id> --text <text> [flags]
```

**Flags:**
- `--text string` — Text to insert (required)
- `--at int` — Position to insert at (1-based index, default: 1)
- `--content-format string` — Content format: `markdown` (default), `plaintext`, or `richformat`

Position 1 is the start of the document content. Use `gws docs read <id> --include-formatting` to see element positions.

### replace — Find and replace text

```bash
gws docs replace <document-id> --find <text> --replace <text> [flags]
```

**Flags:**
- `--find string` — Text to find (required)
- `--replace string` — Replacement text (required)
- `--match-case` — Case-sensitive matching (default: true)

### replace-content — Replace all document content

```bash
gws docs replace-content <document-id> --text "# New content"
gws docs replace-content <document-id> --file ./content.md
```

**Flags:**
- `--text string` — Replacement text
- `--file string` — Read content from file (alternative to --text)
- `--content-format string` — Content format: markdown (default), plaintext, or richformat

Replaces the entire document body while preserving the doc ID, permissions, comments, and revision history. Provide exactly one of `--text` or `--file`.

### delete — Delete content

```bash
gws docs delete <document-id> --from <pos> --to <pos>
```

**Flags:**
- `--from int` — Start position (1-based index, required)
- `--to int` — End position (1-based index, required)

Use `gws docs read <id> --include-formatting` to see position indices.

### add-table — Add a table

```bash
gws docs add-table <document-id> [flags]
```

**Flags:**
- `--rows int` — Number of rows (default: 3)
- `--cols int` — Number of columns (default: 3)
- `--at int` — Position to insert at (1-based index, default: 1)

### format — Format text style

```bash
gws docs format <document-id> [flags]
```

**Flags:**
- `--from int` — Start position (1-based index, required)
- `--to int` — End position (1-based index, required)
- `--bold` — Make text bold
- `--italic` — Make text italic
- `--font-size int` — Font size in points
- `--color string` — Text color (hex, e.g., "#FF0000")