Overview

Manage Google Sheets from the command line: read, write, import/export data across multiple accounts and spreadsheets.

:sparkles: Features

   ✔️ OAuth 2.0 authentication - secure access without service accounts    ✔️ Multi-account support - manage personal, work, and other Google accounts    ✔️ Interactive Drive browsing - select spreadsheets directly from Google Drive    ✔️ Active context system - set account/spreadsheet/sheet once, use everywhere    ✔️ Data operations - read, write, append with markdown/CSV/JSON formats    ✔️ LLM-friendly - designed for AI integrations like Claude Code

:rocket: Quick Start

# 1. Install
npm install -g sheet-cmd

# 2. Setup Google OAuth credentials
# → See "Google Cloud Console Setup" section below

# 3. Add your Google account
sheet-cmd account add
# → Follow the setup instructions
# → Paste Client ID and Client Secret
# → Browser opens for authentication
# → Grant permissions

# 4. Add a spreadsheet
sheet-cmd spreadsheet add
# → Browse and select from Google Drive

# 5. Select a sheet
sheet-cmd sheet select
# → Choose sheet to work with

# 6. Start using!
sheet-cmd sheet read

To use sheet-cmd, you need OAuth 2.0 credentials from Google Cloud Console:

1. Go to Google Cloud Console

2. Create or select a project

• May require setting up billing (free tier available)

3. Enable APIs

• Go to "APIs & Services" > "Library"
• Search and enable "Google Sheets API"
• Search and enable "Google Drive API"

4. Configure OAuth Consent Screen

• Go to: OAuth consent screen
• User Type: External
• App name: sheet-cmd (or any name)
• User support email: your email
• Developer contact: your email
• Click "SAVE AND CONTINUE"

5. Add Scopes

• Go to: Add scopes
• Click "ADD OR REMOVE SCOPES"
• Search and add:
  • .../auth/spreadsheets
  • .../auth/drive.readonly
• Click "UPDATE" then "SAVE AND CONTINUE"

6. Add Test Users

• Go to: Add test users
• Click "ADD USERS"
• Add your email address
• Click "SAVE AND CONTINUE"

7. Create OAuth 2.0 Client ID

• Go to: Credentials
• Click "CREATE CREDENTIALS" > "OAuth client ID"
• Application type: Desktop app
• Name: sheet-cmd
• Click "CREATE"
• Copy the Client ID and Client Secret

Note: The first time you authenticate, you'll see an "unverified app" warning. This is normal for apps in testing mode. Click "Advanced" → "Go to [app name] (unsafe)" to proceed.

:bulb: Usage

All commands use the active account, active spreadsheet, and active sheet by default. Set once, use everywhere.

Account Commands

add - Add a Google account via OAuth

sheet-cmd account add

list - List all configured Google accounts

sheet-cmd account list

select - Select active Google account

sheet-cmd account select

remove - Remove a Google account

sheet-cmd account remove

reauth - Re-authenticate the active account

sheet-cmd account reauth

Spreadsheet Commands

add - Add a new spreadsheet (interactive by default, use --id for manual)

sheet-cmd spreadsheet add

list - List all configured spreadsheets

sheet-cmd spreadsheet list

select - Select a different spreadsheet (sets as active)

sheet-cmd spreadsheet select

active - Show the currently active spreadsheet

sheet-cmd spreadsheet active

remove - Remove a spreadsheet configuration

sheet-cmd spreadsheet remove

Sheet Commands

list - List all sheets in a spreadsheet

sheet-cmd sheet list

select - Select a sheet (sets as active)

sheet-cmd sheet select

read - Read the complete content of a sheet

sheet-cmd sheet read -n "Sheet1"
sheet-cmd sheet read -n "Sheet1" -o markdown
sheet-cmd sheet read -n "Sheet1" -r "A1:B10"
sheet-cmd sheet read -n "Sheet1" -e output.csv

add - Add a new sheet to the spreadsheet

sheet-cmd sheet add -n "NewSheet"

remove - Remove a sheet from the spreadsheet

sheet-cmd sheet remove -n "OldSheet"

rename - Rename a sheet in the spreadsheet

sheet-cmd sheet rename -n "OldName" --new-name "NewName"

copy - Copy a sheet to a new sheet

sheet-cmd sheet copy -n "Sheet1" --to "Sheet1 Copy"

write - Write to a specific cell or range of cells

sheet-cmd sheet write -n "Sheet1" -c A1 -v "Hello"
sheet-cmd sheet write -n "Sheet1" -r A1:B2 -v "v1,v2;v3,v4"
sheet-cmd sheet write -n "Sheet1" -r A1:B2 -v "v1,v2;v3,v4" --no-preserve

append - Append a new row to the end of the sheet

sheet-cmd sheet append -n "Sheet1" -v "val1,val2,val3"

import - Import CSV file to a sheet

sheet-cmd sheet import -n "Sheet1" -f data.csv
sheet-cmd sheet import -n "Sheet1" -f data.csv --skip-header

export - Export sheet data to JSON or CSV format

sheet-cmd sheet export -n "Sheet1" -f json -o output.json
sheet-cmd sheet export -n "Sheet1" -f csv -o output.csv

row-add - Add a row to the sheet

sheet-cmd sheet row-add -r 5 --above
sheet-cmd sheet row-add -r 5 --below --formulas
sheet-cmd sheet row-add -r 5 --below --formulas --count 3

row-remove - Remove a row from the sheet

sheet-cmd sheet row-remove -r 5
sheet-cmd sheet row-remove -r 5 --count 3
sheet-cmd sheet row-remove -r 10 --above --count 5

Update

Update sheet-cmd to latest version

sheet-cmd update

Completion Commands

install - Install shell completion for your current shell

sheet-cmd completion install

# Add Google account via OAuth
sheet-cmd account add

# List all accounts (* = active)
sheet-cmd account list

# Select active account (interactive)
sheet-cmd account select

# Remove account (interactive)
sheet-cmd account remove

# Re-authenticate active account
sheet-cmd account reauth

# Add spreadsheet (interactive - browse Google Drive)
sheet-cmd spreadsheet add

# Add spreadsheet manually by ID
sheet-cmd spreadsheet add --id "1ABC..."

# List all spreadsheets (* = active)
sheet-cmd spreadsheet list

# Select active spreadsheet (interactive)
sheet-cmd spreadsheet select

# Select spreadsheet by ID
sheet-cmd spreadsheet select --id "1ABC..."

# Show currently active spreadsheet
sheet-cmd spreadsheet active

# Remove spreadsheet (interactive)
sheet-cmd spreadsheet remove

# Remove spreadsheet by ID
sheet-cmd spreadsheet remove --id "1ABC..."

# List all sheets in spreadsheet
sheet-cmd sheet list

# Select active sheet (interactive)
sheet-cmd sheet select

# Select sheet by name
sheet-cmd sheet select --name "Sheet1"

# Add a new sheet
sheet-cmd sheet add --name "NewSheet"

# Remove a sheet (uses active if --name not provided)
sheet-cmd sheet remove
sheet-cmd sheet remove --name "OldSheet"

# Rename a sheet (uses active if --name not provided)
sheet-cmd sheet rename --new-name "NewName"
sheet-cmd sheet rename --name "OldName" --new-name "NewName"

# Copy a sheet (uses active if --name not provided)
sheet-cmd sheet copy --to "Sheet1 Copy"
sheet-cmd sheet copy --name "Sheet1" --to "Sheet1 Copy"

# Read sheet content (uses active sheet if --name not provided)
sheet-cmd sheet read
sheet-cmd sheet read --name "Sheet1"
sheet-cmd sheet read --output csv
sheet-cmd sheet read --formulas
sheet-cmd sheet read --export output.md

# Write to single cell (uses active sheet if --name not provided)
sheet-cmd sheet write --cell A1 --value "Hello"
sheet-cmd sheet write --name "Sheet1" --cell A1 --value "Hello"

# Write to range (uses active sheet if --name not provided)
sheet-cmd sheet write --range A1:B2 --value "v1,v2;v3,v4"
sheet-cmd sheet write --name "Sheet1" --range A1:B2 --value "v1,v2;v3,v4"

# Append row (uses active sheet if --name not provided)
sheet-cmd sheet append --value "col1,col2,col3"
sheet-cmd sheet append --name "Sheet1" --value "col1,col2,col3"

Note: For write command, use , to separate columns and ; to separate rows

# Import CSV (uses active sheet if --name not provided)
sheet-cmd sheet import --file data.csv
sheet-cmd sheet import --name "Sheet1" --file data.csv
sheet-cmd sheet import --file data.csv --skip-header

# Export to JSON (uses active sheet if --name not provided)
sheet-cmd sheet export --format json --output output.json
sheet-cmd sheet export --name "Sheet1" --format json --output output.json

# Export to CSV (uses active sheet if --name not provided)
sheet-cmd sheet export --format csv --output output.csv
sheet-cmd sheet export --name "Sheet1" --format csv --output output.csv

# Export specific range
sheet-cmd sheet export --range B2:I25 --format csv --output output.csv

# Update to latest version
sheet-cmd update

# Install shell completion (bash/zsh)
sheet-cmd completion install

:package: Additional Information

Prerequisites: Node.js 18+, Google Account, Linux/macOS/Windows

Configuration files are stored in:

• Linux/WSL: ~/.config/sheet-cmd/
• macOS: ~/Library/Preferences/sheet-cmd/
• Windows: %APPDATA%/sheet-cmd/

Files:

• user_metadata.json - Stores accounts, active selections, and spreadsheets
• config.json - Stores general settings

Example structure:

{
  "config_path": "~/.config/sheet-cmd/config.json",
  "activeAccount": "[email protected]",
  "accounts": {
    "[email protected]": {
      "email": "[email protected]",
      "oauth": {
        "client_id": "xxx.apps.googleusercontent.com",
        "client_secret": "xxx",
        "refresh_token": "xxx",
        "access_token": "xxx",
        "expiry_date": 1234567890
      },
      "activeSpreadsheet": "my-budget",
      "spreadsheets": {
        "my-budget": {
          "spreadsheet_id": "1ABC...",
          "activeSheet": "monthly"
        }
      }
    }
  }
}

Security: All OAuth tokens are stored locally and automatically refreshed before expiry.

Sheet CMD is designed to be LLM-friendly, making it easy for AI tools like Claude Code to interact with your Google Sheets data.

Why this matters:

• Simple command structure that LLMs can easily understand
• Active context system reduces command complexity
• Clear output formats (markdown, CSV, JSON)
• OAuth 2.0 means no service account credentials to manage
• Multi-account support for different contexts

Example Claude Code workflow:

# Claude can read your budget spreadsheet
sheet-cmd sheet read --name "Budget" --output markdown

# Process the data and write results back
sheet-cmd sheet write --name "Analysis" --cell A1 --value "Summary"

# Export for further analysis
sheet-cmd sheet export --name "Data" --format json --output data.json

To completely remove sheet-cmd:

# 1. Remove shell completions (if installed)
sheet-cmd completion uninstall

# 2. Uninstall the package
npm uninstall -g sheet-cmd

# 3. (Optional) Remove configuration files
# Linux/WSL: rm -rf ~/.config/sheet-cmd/
# macOS: rm -rf ~/Library/Preferences/sheet-cmd/
# Windows: Remove %APPDATA%/sheet-cmd/

For local development:

# Clone repository
git clone https://github.com/lucasvtiradentes/sheet-cmd.git
cd sheet-cmd

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev -- sheet list

# Run tests
npm run test
npm run test:e2e

# Type checking
npm run typecheck

# Linting
npm run lint