ReleasedCLI

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
sheets-cli mark

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.

Back to workshop →

Tags
  • CLI
  • Google Sheets
  • Open Source