sheets-cli

Read, write, and update Google Sheets data via CLI. Use when the user asks to read spreadsheet data, update cells, append rows, or work with Google Sheets. Triggers on mentions of spreadsheets, sheets, Google Sheets, tabular data in the cloud, or specific sheet names like "Projects" or "Tasks".

install

source · Clone the upstream repo

git clone https://github.com/gmickel/sheets-cli

Claude Code · Install into ~/.claude/skills/

git clone --depth=1 https://github.com/gmickel/sheets-cli ~/.claude/skills/gmickel-sheets-cli-sheets-cli

manifest: SKILL.md

source content

sheets-cli

CLI for Google Sheets primitives. Read tables, append rows, update cells by key or index, batch operations.

Installation:
sheets-cli
is already installed and available in the user's PATH. Run commands directly—no installation needed.

Quick Reference

# Find spreadsheet by name
sheets-cli sheets find --name "Projects"

# List sheets/tabs
sheets-cli sheets list --spreadsheet <id-or-url>

# Read table data
sheets-cli read table --spreadsheet <id> --sheet "Sheet1" --limit 100

# Update by key column (preferred - rows can shift)
sheets-cli update key --spreadsheet <id> --sheet "Projects" \
  --key-col "Name" --key "Acme" --set '{"Status":"Done"}'

# Append row
sheets-cli append --spreadsheet <id> --sheet "Projects" \
  --values '{"Name":"NewCo","Status":"Active"}'

Workflow Pattern

Always follow read → decide → dry-run → apply:

# 1. Understand current state
sheets-cli read table --sheet "Tasks" --limit 100

# 2. Dry-run first
sheets-cli update key --sheet "Tasks" --key-col "ID" --key "TASK-42" \
  --set '{"Status":"Complete"}' --dry-run

# 3. Apply if dry-run looks correct
sheets-cli update key --sheet "Tasks" --key-col "ID" --key "TASK-42" \
  --set '{"Status":"Complete"}'

Commands

Auth (Setup)

sheets-cli auth login --credentials <oauth-client.json>
sheets-cli auth status
sheets-cli auth logout

Find Spreadsheet by Name

sheets-cli sheets find --name "<query>" [--limit 10]

Searches Google Drive for spreadsheets matching the name. Returns ID, name, URL.

Requires Google Drive API enabled in the project.

List Sheets/Tabs

sheets-cli sheets list --spreadsheet <id>

Sheet Info

sheets-cli sheet info --spreadsheet <id> --sheet "<name>"
sheets-cli sheet info --spreadsheet <id> --gid <gid>

Get sheet metadata by name or GID.

Get Header Row

sheets-cli header --spreadsheet <id> --sheet "<name>" [--header-row N]

Returns column headers. Auto-detects header row if not specified.

Read Table Data

sheets-cli read table --spreadsheet <id> --sheet "<name>" [--limit N] [--raw]

Returns

{ headers: ["_row", ...], rows: [{_row: N, ...}, ...], headerRow: N }

Each row includes

_row

- the absolute sheet row number for use with

update row

Read Raw Range

sheets-cli read range --spreadsheet <id> --range "Sheet1!A1:B10"

Append Row

sheets-cli append --spreadsheet <id> --sheet "<name>" \
  --values '<json>' [--dry-run]

JSON object with column names as keys. Column matching is case-insensitive with normalized whitespace.

Update by Key (Preferred)

sheets-cli update key --spreadsheet <id> --sheet "<name>" \
  --key-col "<column>" --key "<value>" --set '<json>' \
  [--allow-multi] [--dry-run]

Finds rows where

key-col

equals

key

, updates columns from

--set

. Throws if multiple matches unless

--allow-multi

Update by Row Index

sheets-cli update row --spreadsheet <id> --sheet "<name>" \
  --row <n> --set '<json>' [--dry-run]

Updates specific row by 1-indexed row number. Use

_row

from

read table

output directly.

Row Numbering

```
read table
```
returns
```
headerRow
```
and rows with
```
_row
```
field
```
_row
```
is the absolute sheet row number - use directly with
```
update row --row
```
Example:
```
headerRow: 2
```
means headers on row 2, first data row is
```
_row: 3
```
Never calculate row numbers manually - always use
```
_row
```
from read output

Set Range

sheets-cli set range --spreadsheet <id> --range "Sheet1!A1:B2" \
  --values '<2d-json-array>' [--dry-run]

Batch Operations

sheets-cli batch --spreadsheet <id> --ops '<json-array>' [--dry-run]

Operations:

append

updateRow

updateKey

setRange

Global Options

Option	Description
`--spreadsheet <id>`	Spreadsheet ID or full URL
`--dry-run`	Preview without applying
`--header-row <n>`	Header row (auto-detects if omitted)
`--value-input <mode>`	`USER_ENTERED` (default) or `RAW`

Output Format

All commands return JSON:

{
  "ok": true,
  "cmd": "update key",
  "spreadsheetId": "...",
  "sheet": "Projects",
  "result": { "matchedRows": 1, "updatedCells": 2 }
}

Errors:

{
  "ok": false,
  "cmd": "update key",
  "error": { "code": "VALIDATION_ERROR", "message": "..." }
}

Best Practices

Use
sheets find
to get spreadsheet ID from name
--spreadsheet
accepts URLs - paste full Google Sheets URL directly
Prefer key-based updates over row indices - rows shift on insert/delete
Always dry-run before writes
Check
ok
field in response before proceeding
Batch related operations for atomicity
Column names match case-insensitively with normalized whitespace
Header row auto-detects - skips empty rows to find first data row
Headerless sheets:
```
read table
```
returns columns as
```
A
```
,
```
B
```
, ...; use column letters for
```
--set
```
/
```
--key-col
```
Column letter vs header: When a key like
```
ID
```
or
```
URL
```
matches both a header name and a column letter pattern, the header match wins. Column letter addressing (
```
A
```
,
```
B
```
,
```
AA
```
) is only used as fallback when no header matches
Empty sheets:
```
append
```
can bootstrap by writing a header row from JSON keys
read table --range
accepts
```
A1:Z
```
(auto-prefixed with the sheet)

Exit Codes

Code	Meaning
0	Success
10	Validation error
20	Auth error
30	Permission error
40	API/transient error