---
name: gog-docs
description: "Google Docs via the gog CLI: read/export document text and structure, list and target tabs, insert/append/replace content as markdown or plain text, format, and manage comments. Use for Docs automation that needs precise tab/range targeting and JSON output."
---

# gog docs

Docs reads and writes with parseable output. Pick the account on every call with
`--account <email>` (or set `GOG_ACCOUNT`).

## Reads

```bash
gog --account you@example.com docs cat <documentId> --json --wrap-untrusted
gog --account you@example.com docs cat <documentId> --raw           # resolve UTF-16 ranges
gog --account you@example.com docs list-tabs <documentId> --json
gog --account you@example.com docs structure <documentId> --json
gog --account you@example.com docs headings list <documentId> --json
gog --account you@example.com docs export <documentId> --format pdf -o out.pdf
```

## Writes

```bash
gog --account you@example.com docs create --title "Temp - draft" --json
gog --account you@example.com docs write <documentId> --append --text '...'
gog --account you@example.com docs write <documentId> --tab "Data" --markdown --replace --file data.md
gog --account you@example.com docs update <documentId> --tab "Data" --markdown --file block.md
gog --account you@example.com docs update <documentId> --tab "Data" --replace-range START:END --text 'replacement'
gog --account you@example.com docs find-replace <documentId> --find "foo" --replace "bar" --dry-run
```

Tab/range rules:
- Discover tab titles/IDs with `docs list-tabs` before targeting `--tab`.
- `docs write --markdown --replace --tab <tab>` replaces a whole tab; `docs
  update --markdown --tab <tab>` inserts/appends without replacing.
- `START:END` is a Google Docs UTF-16 API range — resolve it from `docs cat
  --raw`/`docs raw`, never guess. `--replace-range` and `--index` are exclusive.

## Safety

- `--dry-run` first on `find-replace`/`update`; deleting tabs/docs needs `--force`.
- When testing creation, name artifacts with a clear temp prefix and trash them after.
- stdout is data (`--json`/`--plain`); hints go to stderr. `--no-input` in automation.

## Discovery

`gog docs --help` · `gog docs <cmd> --help` · `gog schema docs <cmd> --json`
Reference: <https://gogcli.sh/>
