The Problem
Managing Google Sheets from the command line is cumbersome: the native API requires OAuth handling, index‑based updates are fragile, and output is not machine‑readable. Teams that automate reporting or integrate spreadsheet data into scripts need a deterministic, JSON‑driven interface that can also be invoked by AI agents.
What This Does
sheets-cli provides a small TypeScript‑based CLI that wraps the Google Sheets and Drive APIs. Core logic lives in src/cli.ts (the entry point) and supporting modules such as src/sheets.ts (API calls), src/auth.ts (OAuth flow), src/output.ts (JSON formatting), and src/skill.ts (agent‑skill metadata). The repository ships with ready‑made Agent Skills (.claude/skills/sheets-cli.md) for Claude Code and OpenAI Codex, allowing an LLM to call the CLI without custom prompting. The CLI is built with Bun (bun install, bun run build) and outputs deterministic JSON, which downstream tools can pipe into.
How To Use It
Setup (all commands run from the repository root):
Clone and install
git clone https://github.com/gmickel/sheets-cli.git cd sheets-cli bun install # installs deps from package.json bun run build # compiles TypeScript to ./dist
The compiled binary is ./dist/sheets-cli.
Configuration
Enable Google Sheets API and Google Drive API in a Google Cloud project. Create an OAuth 2.0 Desktop client and download the JSON credentials file. Authenticate once:
./dist/sheets-cli auth login --credentials ./clientsecret.json
The CLI starts a local listener (http://localhost:3847) to capture the OAuth code.
Optionally set a default spreadsheet to avoid repeating --spreadsheet:
export SHEETSCLIDEFAULTSPREADSHEET_ID="your-spreadsheet-id"
Running commands (examples taken verbatim from README.md):
List sheets in a spreadsheet
./dist/sheets-cli sheets list --spreadsheet <id>
Read a table as structured JSON (limit 5 rows) ./dist/sheets-cli read table --spreadsheet <id> --sheet "Sheet1" --limit 5
Append a row
./dist/sheets-cli append --spreadsheet <id> --sheet "Sheet1" \ --values '{"Name":"New Item","Status":"Active"}'
Update a row by key column
./dist/sheets-cli update key --spreadsheet <id> --sheet "Projects" \ --key-col "Name" --key "Acme" --set '{"Status":"Done"}'
Agent integration is automatic when the skill files in .claude/ are imported by Claude Code or OpenAI Codex.
Real‑World Use
A CI pipeline that generates weekly status reports can invoke:
REPORT=$(./dist/sheets-cli read table --sheet "Metrics" --limit 20) curl -X POST -H "Content-Type: application/json" -d "$REPORT" https://example.com/report
The JSON payload feeds directly into downstream analytics without fragile cell coordinates.
Code Health & Issues
Medium – SDLC – No CI/CD workflow (no .github/workflows or similar). Automated testing must be run manually (bun test). Medium – SDLC – No LICENSE file; redistribution and commercial use are ambiguous. Low – Build reproducibility – package.json is present but no lockfile (bun.lock exists but is not a full lockfile); exact dependency versions may drift. Low – Test coverage – Six test files (src/tests/*.test.ts) exist, but there is no coverage report or integration with a CI step. Low – Documentation – Core commands are documented in README.md; however, the agent‑skill usage is only described in .claude/skills/sheets-cli.md and lacks versioning. Low – Error handling – src/auth.ts and src/sheets.ts perform network calls without explicit retry logic; transient API failures could cause CLI exits.
Overall the codebase is small, typed (typescript), and organized with clear module boundaries. Tests cover authentication, CLI parsing, and sheet operations, indicating a reasonable baseline quality.
The Bottom Line
sheets-cli delivers a focused, TypeScript‑based CLI for deterministic Google Sheets manipulation and includes ready‑made LLM agent skills. It is well‑structured and test‑backed but lacks CI automation, a clear license, and robust error handling. It suits small‑to‑medium automation projects where a lightweight, JSON‑oriented interface to Sheets is needed, provided the team can manage the missing CI and licensing considerations.