sheets-cli

Composable Google Sheets primitives for humans and agents

Installation • Quick Start • Commands • For Agents

📢 New Project: Check out GNO — local hybrid search for your documents (Markdown, PDF, Word, Excel). Combines BM25 + vector search with MCP integration for AI agents. Great companion to sheets-cli: search your local docs, query your cloud sheets.

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

# 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

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

2. Create OAuth Credentials

1. Go to Google Cloud Console → Credentials
2. Create OAuth 2.0 Client ID → Desktop app
3. 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]