sheets-cli.
Google Sheets for humans and agents.
A fast, deterministic CLI for reading and writing Google Sheets. Key-based updates instead of fragile row indices. Batch operations for atomic multi-step workflows. JSON everywhere. Designed for humans at the terminal and AI agents that need programmatic spreadsheet access.
- Stack
- Bun + TypeScript
- Platforms
- Claude Code, Codex
- License
- MIT

01 / Why key updates
Stable updates.
Row numbers change when data is sorted, filtered, or inserted. Keys don't.
Fragile
update --row 5 --set Status=Done
Row 5 today might be row 8 tomorrow.
Stable
update key --key-col Name \ --key Acme --set Status=Done
Finds "Acme" wherever it is.
02 / Commands
Four verbs.
- 01
read table
Extract a table as JSON with auto header detection.
- 02
update key
Modify cells by column value, not fragile row index.
- 03
append
Add rows with JSON values.
- 04
batch
Execute multiple operations atomically.
03 / Features
What's in the box.
- 01
Key-based updates
Match on a key column instead of a row number. Data moves; updates still work.
- 02
Batch operations
Multiple reads, writes, and updates in one atomic API request.
- 03
JSON I/O
All input and output structured JSON. Deterministic, parseable, agent-friendly.
- 04
Dry-run
Preview changes before applying. See exactly what will happen.
- 05
Agent skills
Installs as a skill for Claude Code and OpenAI Codex. AI discovers it automatically.
- 06
Structured errors
Exit codes and messages designed for automation. Validation, auth, permissions, API errors distinct.
04 / Agents
Agent integration.
Install as a skill and your AI assistant can read, write, and update spreadsheets directly.
# Claude Code (project) sheets-cli install-skill # Personal use sheets-cli install-skill --global # OpenAI Codex sheets-cli install-skill --codex
Example prompts
- "Read the Projects sheet and summarize active tasks."
- "Update the status of Acme to Done in the tracker."
- "Append today's metrics to the dashboard sheet."
05 / Quick start
Install + authenticate.
git clone https://github.com/gmickel/sheets-cli.git cd sheets-cli bun install && bun run build # Authenticate sheets-cli auth login --credentials ./client_secret.json # Start using sheets-cli read table --sheet "Sheet1"
06 / Spec
Stack + use cases.
- Stack
- Bun + TypeScript
- Output
- Structured JSON
- Auth
- OAuth 2.0 (Desktop)
- Runtime
- Bun
- License
- MIT
Use cases
- CI/CD pipelines · Deployment trackers.
- Data ingestion · Batch append from scripts.
- AI workflows · Agents managing their own sheets.
- Manual ops · Quick terminal updates.
- CLI
- Google Sheets
- Open Source