---
name: gog-sheets
description: "Google Sheets via the gog CLI: read ranges, write/append/clear values, batch-update many ranges in one call, format, manage tabs, named ranges, tables, and charts. Use for spreadsheet automation that needs A1 ranges and JSON output."
---

# gog sheets

Sheets 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 sheets get <spreadsheetId> 'Sheet1!A1:D20' --json --wrap-untrusted
gog --account you@example.com sheets metadata <spreadsheetId> --json
gog --account you@example.com sheets read-format <spreadsheetId> 'Sheet1!A1' --json
gog --account you@example.com sheets export <spreadsheetId> --format csv -o out.csv
```

## Writes

```bash
gog --account you@example.com sheets update <spreadsheetId> 'Sheet1!A1' --values-json '[["hello"]]'
gog --account you@example.com sheets append <spreadsheetId> 'Sheet1!A:C' --values-json '[["a","b","c"]]'
gog --account you@example.com sheets batch-update <spreadsheetId> --data-json @updates.json
gog --account you@example.com sheets clear <spreadsheetId> 'Sheet1!A1:D20'
gog --account you@example.com sheets create --title "Temp - data" --json
gog --account you@example.com sheets add-tab <spreadsheetId> --title "Data"
```

For multi-range writes prefer `batch-update` (one API request, accepts inline
JSON or `@file`) over loops of `update`.

## Safety

- `clear`, `delete-tab`, and overwriting `update`/`batch-update` lose existing
  data — confirm the range and spreadsheet id; `delete-tab` needs `--force`.
- Name test spreadsheets with a clear temp prefix and trash them after.
- stdout is data (`--json`/`--plain`); hints go to stderr. `--no-input` in automation.

## Discovery

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