https://github.com/lucasvtiradentes/sheet-cmd

A CLI tool to interact with Google Sheets - perfect for LLM integrations
https://github.com/lucasvtiradentes/sheet-cmd

automation claude-code cli google-sheets llm productivity sheets-api typescript

Last synced: about 1 month ago
JSON representation

A CLI tool to interact with Google Sheets - perfect for LLM integrations

Host: GitHub
URL: https://github.com/lucasvtiradentes/sheet-cmd
Owner: lucasvtiradentes
License: mit
Created: 2025-10-03T03:55:17.000Z (5 months ago)
Default Branch: main
Last Pushed: 2025-10-03T05:22:19.000Z (5 months ago)
Last Synced: 2025-10-03T05:23:10.088Z (5 months ago)
Topics: automation, claude-code, cli, google-sheets, llm, productivity, sheets-api, typescript
Language: TypeScript
Size: 65.4 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

Sheet CMD

Quick Start • Usage • Additional Information

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

```bash
# 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
```

Google Cloud Console Setup

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

**1. Go to [Google Cloud Console](https://console.cloud.google.com/)**

**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](https://console.cloud.google.com/apis/credentials/consent)
- 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](https://console.cloud.google.com/auth/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](https://console.cloud.google.com/auth/audience)
- Click "ADD USERS"
- Add your email address
- Click "SAVE AND CONTINUE"

**7. Create OAuth 2.0 Client ID**
- Go to: [Credentials](https://console.cloud.google.com/apis/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

```bash
sheet-cmd account add
```

**list** - List all configured Google accounts

```bash
sheet-cmd account list
```

**select** - Select active Google account

```bash
sheet-cmd account select
```

**remove** - Remove a Google account

```bash
sheet-cmd account remove
```

**reauth** - Re-authenticate the active account

```bash
sheet-cmd account reauth
```

### Spreadsheet Commands

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

```bash
sheet-cmd spreadsheet add
```

**list** - List all configured spreadsheets

```bash
sheet-cmd spreadsheet list
```

**select** - Select a different spreadsheet (sets as active)

```bash
sheet-cmd spreadsheet select
```

**active** - Show the currently active spreadsheet

```bash
sheet-cmd spreadsheet active
```

**remove** - Remove a spreadsheet configuration

```bash
sheet-cmd spreadsheet remove
```

### Sheet Commands

**list** - List all sheets in a spreadsheet

```bash
sheet-cmd sheet list
```

**select** - Select a sheet (sets as active)

```bash
sheet-cmd sheet select
```

**read** - Read the complete content of a sheet

```bash
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

```bash
sheet-cmd sheet add -n "NewSheet"
```

**remove** - Remove a sheet from the spreadsheet

```bash
sheet-cmd sheet remove -n "OldSheet"
```

**rename** - Rename a sheet in the spreadsheet

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

**copy** - Copy a sheet to a new sheet

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

**write** - Write to a specific cell or range of cells

```bash
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

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

**import** - Import CSV file to a sheet

```bash
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

```bash
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

```bash
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

```bash
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

```bash
sheet-cmd update
```

### Completion Commands

**install** - Install shell completion for your current shell

```bash
sheet-cmd completion install
```

Account Management

```bash
# 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
```

Spreadsheet Management

```bash
# 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..."
```

Sheet Management

```bash
# 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"
```

Data Operations

```bash
# 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/Export

```bash
# 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
```

System Commands

```bash
# 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

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:**
```json
{
"config_path": "~/.config/sheet-cmd/config.json",
"activeAccount": "user@gmail.com",
"accounts": {
"user@gmail.com": {
"email": "user@gmail.com",
"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.

LLM Integration

Sheet CMD is designed to be LLM-friendly, making it easy for AI tools like [Claude Code](https://www.anthropic.com/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:**
```bash
# 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
```

Uninstallation

To completely remove sheet-cmd:

```bash
# 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/
```

Development setup

For local development:

```bash
# 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
```

---

Made with ❤️ by Lucas Vieira

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/lucasvtiradentes/sheet-cmd

Awesome Lists containing this project

README

Sheet CMD