sheets-cli

Composable Google Sheets primitives for humans and agents

Installation • Quick Start • Commands • For Agents

Fast, deterministic CLI for Google Sheets. Read tables, append rows, update cells by key or index, batch operations—all with JSON output for programmatic consumption.

# Read a sheet as structured data
sheets-cli read table --sheet "Projects" --limit 10

# Update by key column (no fragile row indices)
sheets-cli update key --sheet "Projects" --key-col "Name" --key "Acme" --set '{"Status":"Done"}'

🆕 Agent Skills — Install as a skill for Claude Code, OpenAI Codex, or VS Code (Insiders preview; enable chat.useAgentSkills). The agent automatically discovers sheets-cli when you mention spreadsheets. See For Agents.

Installation

Prerequisites: Bun runtime

git clone https://github.com/gmickel/sheets-cli.git
cd sheets-cli
bun install
bun run build

# Binary at ./dist/sheets-cli

Add to PATH

# Symlink
ln -s "$(pwd)/dist/sheets-cli" /usr/local/bin/sheets-cli

# Or add to shell config
echo 'export PATH="$PATH:/path/to/sheets-cli/dist"' >> ~/.zshrc

Quick Start

1. Enable APIs

Go to Google Cloud Console → APIs
Enable Google Sheets API
Enable Google Drive API (required for sheets find command)

2. Create OAuth Credentials

Go to Google Cloud Console → Credentials
Create OAuth 2.0 Client ID → Desktop app
Download the JSON file

Desktop apps auto-allow localhost redirects. CLI captures OAuth code via http://localhost:3847.

3. Authenticate

sheets-cli auth login --credentials ./client_secret.json

Browser opens → authorize → done.

4. Set Default Spreadsheet (optional)

# Set env var to avoid passing --spreadsheet every time
export SHEETS_CLI_DEFAULT_SPREADSHEET_ID="your-spreadsheet-id"

Get the ID from your sheet URL: docs.google.com/spreadsheets/d/<ID>/edit

5. Use

sheets-cli sheets list --spreadsheet <id>
sheets-cli read table --spreadsheet <id> --sheet "Sheet1" --limit 5
sheets-cli append --spreadsheet <id> --sheet "Sheet1" --values '{"Name":"New Item","Status":"Active"}'

Commands

Auth

sheets-cli auth login --credentials <file> [--token-store <path>]
sheets-cli auth status
sheets-cli auth logout

Metadata

sheets-cli sheets list [--spreadsheet <id>]
sheets-cli sheets find --name "<query>" [--limit 10]  # Search by name
sheets-cli sheet info --sheet "<name>" [--spreadsheet <id>]
sheets-cli sheet info --gid <gid> [--spreadsheet <id>]
sheets-cli header --sheet "<name>" [--header-row 1]

Read

sheets-cli read table --sheet "<name>" [--limit 500] [--range "A1:Z500"] [--raw]
sheets-cli read range --range "<sheet>!A1:Z50"

Write

sheets-cli append --sheet "<name>" --values '<json>' [--value-input USER_ENTERED|RAW] [--dry-run]
sheets-cli update row --sheet "<name>" --row 12 --set '<json>' [--dry-run]
sheets-cli update key --sheet "<name>" --key-col "Col" --key "Val" --set '<json>' [--dry-run] [--allow-multi]
sheets-cli set range --range "<sheet>!M2:M2" --values '<json_2d_array>' [--dry-run]
sheets-cli batch --ops '<json>' [--dry-run]

All flags

Flag	Description	Default
`--spreadsheet <id>`	Spreadsheet ID or full URL	env var or required
`--dry-run`	Preview without applying	`false`
`--value-input <mode>`	`USER_ENTERED` or `RAW`	`USER_ENTERED`
`--header-row <n>`	Header row number	Auto-detect
`--limit <n>`	Max rows to return	unlimited
`--raw`	Return unformatted values	`false`
`--allow-multi`	Update multiple matching rows	`false`

JSON Formats

Append/Update values

{"Name": "Acme Corp", "Status": "Active", "Start Date": "2025-01-15"}

Headerless sheets (column letters):

{"A": "Acme Corp", "C": "Active"}

Set range (2D array)

[["Value1", "Value2"], ["Value3", "Value4"]]

Batch operations

[
  {"op": "append", "sheet": "Tasks", "values": {"Name": "New Task"}},
  {"op": "updateRow", "sheet": "Tasks", "row": 5, "set": {"Status": "Done"}},
  {"op": "updateKey", "sheet": "Tasks", "keyCol": "ID", "key": "TASK-123", "set": {"Status": "Active"}},
  {"op": "setRange", "range": "Tasks!A1:B1", "values": [["Col1", "Col2"]]}
]

Output Format

All commands return JSON to stdout:

{
  "ok": true,
  "cmd": "read table",
  "spreadsheetId": "1abc...",
  "sheet": "Projects",
  "result": {
    "headers": ["Name", "Status", "Date"],
    "rows": [{"Name": "Alpha", "Status": "Active", "Date": "2025-01-15"}],
    "headerRow": 1
  }
}

Errors:

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

Exit Codes

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

For Agents

Install Skill

# Claude Code
sheets-cli install-skill           # Project: ./.claude/skills/sheets-cli/SKILL.md
sheets-cli install-skill --global  # Personal: ~/.claude/skills/sheets-cli/SKILL.md

# OpenAI Codex
sheets-cli install-skill --codex   # ~/.codex/skills/sheets-cli/SKILL.md

Installs an Agent Skill that teaches the agent how to use sheets-cli. After installing, the agent automatically discovers sheets-cli when you mention spreadsheets, Google Sheets, or sheet names.

Codex: Requires skills = true in ~/.codex/config.toml under [features]. VS Code: Agent Skills support is in preview and only available in VS Code Insiders. Enable chat.useAgentSkills to use Agent Skills.

Restart the agent after installing to load the skill.

Workflow Pattern

Follow read → decide → dry-run → apply:

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

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

# 3. Apply
sheets-cli update key --sheet "Tasks" --key-col "ID" --key "TASK-42" --set '{"Status":"Complete"}'

Best Practices

Use sheets find to get spreadsheet ID from name
Prefer key-based updates over row indices—rows shift on insert/delete
Always dry-run before writes
Check ok field 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 row with data
Headerless sheets: read table returns columns as A, B, ...; use column letters for --set / --key-col
Empty sheets: append can bootstrap by writing a header row from JSON keys
read table --range accepts A1:Z (auto-prefixed with the sheet)
--spreadsheet accepts URLs—paste full Google Sheets URL directly

Development

bun run dev          # Hot-reload
bun run build        # Compile binary
bun run typecheck    # Type check
bun run lint         # Lint
bun run test         # Tests

License

MIT

_{Built with Bun • Styled for machines and humans alike}

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.claude		.claude
.cursor		.cursor
.github		.github
.vscode		.vscode
src		src
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
SKILL.md		SKILL.md
biome.jsonc		biome.jsonc
bun.lock		bun.lock
lefthook.yml		lefthook.yml
package.json		package.json
prd.md		prd.md
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Repository files navigation

sheets-cli

Installation

Quick Start

1. Enable APIs

2. Create OAuth Credentials

3. Authenticate

4. Set Default Spreadsheet (optional)

5. Use

Commands

Auth

Metadata

Read

Write

JSON Formats

Append/Update values

Set range (2D array)

Batch operations

Output Format

Exit Codes

For Agents

Install Skill

Workflow Pattern

Best Practices

Development

License

About

Uh oh!

Releases

Sponsor this project

Uh oh!

Packages

Languages

Uh oh!

gmickel/sheets-cli

Folders and files

Latest commit

History

Repository files navigation

sheets-cli

Installation

Quick Start

1. Enable APIs

2. Create OAuth Credentials

3. Authenticate

4. Set Default Spreadsheet (optional)

5. Use

Commands

Auth

Metadata

Read

Write

JSON Formats

Append/Update values

Set range (2D array)

Batch operations

Output Format

Exit Codes

For Agents

Install Skill

Workflow Pattern

Best Practices

Development

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Sponsor this project

Uh oh!

Packages 0

Languages

Packages