The Problem Automation scripts that need to read or mutate Google Sheets typically require ad‑hoc HTTP calls, fragile row indexes, and custom OAuth handling. Maintaining those pieces across teams creates duplicated code and brittle integrations.

What This Does sheets-cli packages the Google Sheets API into a deterministic command‑line tool. Core logic lives in src/cli.ts (argument parsing, command dispatch) and src/sheets.ts (API wrappers, header normalisation, range handling). Types and result helpers are in src/types.ts; authentication flows are in src/auth.ts; output formatting lives in src/output.ts. Agent‑specific skill metadata is stored under .claude/skills/sheets-cli.md.

How It Is Wired

  1. Entry point – execution starts at src/cli.ts. The function resolveSpreadsheet (line 26) parses the --spreadsheet option and calls getSheets (line 139).
  2. Command handling – parseJsonObject, parseJsonArray, parseIntOption, and parsePositiveIntOption turn CLI flags into typed values, then invoke the corresponding operation in src/sheets.ts.
  3. Sheets module – src/sheets.ts exports the bulk of the work: getSheetsClient creates an authenticated Google API client via getAuthClient from src/auth.ts. normalizeHeader, escapeSheetName, qualifyRange, isColumnLetter, colToLetter, and colLetterToNumber are the most‑called utilities (9‑7 call sites each). * High‑impact functions (error, output, normalizeHeader) appear in the internal call graph with the widest blast radius (9, 8, 7 distinct callers).
  4. Authentication – src/auth.ts runs a local HTTP server, exchanges the OAuth code, and caches the token. getAuthClient is the only outward‑facing call from the rest of the codebase.
  5. Output – src/output.ts formats JSON success or error payloads and sets the process exit code.

The import graph shows a clean hierarchy: cli.ts → sheets.ts/auth.ts → utility functions. No circular dependencies are present, but two files (src/cli.ts ≈ 745 LOC, src/sheets.ts ≈ 745 LOC) are large enough to impede quick comprehension and increase change‑impact risk.

How To Use It

# Clone and build
git clone https://github.com/moses-y/sheets-cli
cd sheets-cli
bun install          # uses Bun runtime as documented in README
bun run build        # produces ./dist/sheets-cli

Configure Google OAuth:

# Obtain client_secret.json from Google Cloud Console
sheets-cli auth login --credentials ./client_secret.json

Optional default spreadsheet:

export SHEETS_CLI_DEFAULT_SPREADSHEET_ID="1AbCdefGhIjkLmNoPqRstUvWxYz"

Run commands (binary is ./dist/sheets-cli):

./dist/sheets-cli read table --sheet "Projects" --limit 10
./dist/sheets-cli update key --sheet "Projects" --key-col "Name" --key "Acme" --set '{"Status":"Done"}'

Real‑World Use A CI pipeline can publish sprint outcomes to a shared sheet: after a successful build, a script runs ./dist/sheets-cli append --sheet "Deployments" --values '{"Build":"${GITHUB_RUN_ID}","Status":"Success"}'. The same tool can be invoked by Claude Code or OpenAI Codex agents via the skill file in .claude/skills/sheets-cli.md, enabling natural‑language driven spreadsheet updates.

Code Health & Issues

  • High – No LICENSE – repository root lacks a licence file; default is “all rights reserved,” blocking reuse.
  • High – No CI pipeline – 12 source files and tests exist, but .github/ contains only a FUNDING file; no workflow runs builds or tests on push.
  • Medium – No Dependabot – only package.json is present; without a dependabot config security updates are manual.
  • Medium – Oversized files – src/cli.ts and src/sheets.ts each exceed 700 LOC, increasing cognitive load and change‑impact risk. Splitting by responsibility (e.g., separate command dispatch, API client, and utility modules) would reduce blast radius.

The Bottom Line sheets-cli delivers a focused, TypeScript‑based CLI for deterministic Google Sheets operations and integrates with AI agents out of the box. The codebase is functional but lacks essential production safeguards (license, CI, automated dependency updates) and contains two large modules that would benefit from refactoring. It is suitable for teams needing a quick, scriptable Sheets interface, provided they add the missing compliance and automation scaffolding.