GOOGLE SHEETS

CLI

Open Source

sheets-cli

Name: sheets-cli
Author: Gordon Mickel

Google Sheets for humans & agents

← All Apps

Main Site

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 both humans at the terminal and AI agents that need programmatic spreadsheet access.

GitHub

sheets-cli

$ sheets-cli read table --sheet "Projects"

{"ok": true, "result": [...]}

$ sheets-cli update key --key-col "Name" --key "Acme"

Updated row 5: Status → Done

$ sheets-cli batch --ops '[...]'

2 operations completed atomically

COMMANDS

read table

Extract table as JSON with auto header detection

update key

Modify cells by column value, not fragile row index

append

Add rows with JSON values

batch

Execute multiple operations atomically

Why update key?

Traditional spreadsheet APIs update by row number. But row numbers change when data is sorted, filtered, or when rows are inserted.

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.

FEATURES

🔑

Key-Based Updates

Update rows by matching a key column instead of fragile row indices. Data moves? Updates still work.

📦

Batch Operations

Execute multiple reads, writes, and updates in a single API request. Atomic and efficient.

{}

JSON I/O

All input and output uses structured JSON. Deterministic, parseable, AI-friendly.

👁

Dry-Run Mode

Preview changes before applying them. See exactly what will happen without modifying data.

🤖

Agent Skills

Install as a skill for Claude Code, OpenAI Codex, and VS Code. AI discovers it automatically.

⚠

Structured Errors

Exit codes and error messages designed for automation. Validation, auth, permissions, API errors all distinct.

AI Agent Integration

Install as a skill so your AI assistant can read, write, and update spreadsheets on your behalf.

bash

# Claude Code (project)

sheets-cli install-skill

# Personal use

sheets-cli install-skill --global

# OpenAI Codex

sheets-cli install-skill --codex

Example prompts for your AI

"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"

QUICK START

bash

# Clone and build

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"

Stack

Built with: Bun + TypeScript
Output: Structured JSON
Auth: OAuth 2.0 (Desktop app)
Requirements: Bun runtime
License: MIT (Open Source)

Use Cases

›CI/CD pipelines — Update deployment trackers
›Data ingestion — Batch append from scripts
›AI workflows — Let agents manage your sheets
›Manual ops — Quick terminal-based updates

View on GitHub →

sheets-cli

Google Sheets for humans & 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 both humans at the terminal and AI agents that need programmatic spreadsheet access.