{"id":31580965,"url":"https://github.com/lucasvtiradentes/sheet-cmd","last_synced_at":"2026-01-20T17:32:55.437Z","repository":{"id":317793143,"uuid":"1068881029","full_name":"lucasvtiradentes/sheet-cmd","owner":"lucasvtiradentes","description":"A CLI tool to interact with Google Sheets - perfect for LLM integrations","archived":false,"fork":false,"pushed_at":"2025-10-03T05:22:19.000Z","size":67,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T05:23:10.088Z","etag":null,"topics":["automation","claude-code","cli","google-sheets","llm","productivity","sheets-api","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucasvtiradentes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-03T03:55:17.000Z","updated_at":"2025-10-03T05:21:39.000Z","dependencies_parsed_at":"2025-10-03T05:23:18.344Z","dependency_job_id":"3d3bcf01-54e9-420c-9298-ac41324c83ab","html_url":"https://github.com/lucasvtiradentes/sheet-cmd","commit_stats":null,"previous_names":["lucasvtiradentes/sheet-cmd"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/lucasvtiradentes/sheet-cmd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasvtiradentes%2Fsheet-cmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasvtiradentes%2Fsheet-cmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasvtiradentes%2Fsheet-cmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasvtiradentes%2Fsheet-cmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucasvtiradentes","download_url":"https://codeload.github.com/lucasvtiradentes/sheet-cmd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasvtiradentes%2Fsheet-cmd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278924143,"owners_count":26069400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","claude-code","cli","google-sheets","llm","productivity","sheets-api","typescript"],"created_at":"2025-10-05T21:51:32.867Z","updated_at":"2026-01-20T17:32:55.412Z","avatar_url":"https://github.com/lucasvtiradentes.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://www.google.com/sheets/about/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n  \u003cimg width=\"64\" src=\".github/image/sheet.png\" alt=\"Google Sheets logo\"\u003e\n\u003c/a\u003e\n\u003ch2\u003eSheet CMD\u003c/h2\u003e\n\u003cp\u003e\n  \u003ca href=\"#rocket-quick-start\"\u003eQuick Start\u003c/a\u003e • \u003ca href=\"#bulb-usage\"\u003eUsage\u003c/a\u003e • \u003ca href=\"#package-additional-information\"\u003eAdditional Information\u003c/a\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n## Overview\n\nManage Google Sheets from the command line: read, write, import/export data across multiple accounts and spreadsheets.\n\n## :sparkles: Features\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;✔️ **OAuth 2.0 authentication** - secure access without service accounts\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;✔️ **Multi-account support** - manage personal, work, and other Google accounts\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;✔️ **Interactive Drive browsing** - select spreadsheets directly from Google Drive\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;✔️ **Active context system** - set account/spreadsheet/sheet once, use everywhere\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;✔️ **Data operations** - read, write, append with markdown/CSV/JSON formats\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;✔️ **LLM-friendly** - designed for AI integrations like Claude Code\u003cbr\u003e\n\n## :rocket: Quick Start\n\n```bash\n# 1. Install\nnpm install -g sheet-cmd\n\n# 2. Setup Google OAuth credentials\n# → See \"Google Cloud Console Setup\" section below\n\n# 3. Add your Google account\nsheet-cmd account add\n# → Follow the setup instructions\n# → Paste Client ID and Client Secret\n# → Browser opens for authentication\n# → Grant permissions\n\n# 4. Add a spreadsheet\nsheet-cmd spreadsheet add\n# → Browse and select from Google Drive\n\n# 5. Select a sheet\nsheet-cmd sheet select\n# → Choose sheet to work with\n\n# 6. Start using!\nsheet-cmd sheet read\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGoogle Cloud Console Setup\u003c/b\u003e\u003c/summary\u003e\n\nTo use sheet-cmd, you need OAuth 2.0 credentials from Google Cloud Console:\n\n**1. Go to [Google Cloud Console](https://console.cloud.google.com/)**\n\n**2. Create or select a project**\n- May require setting up billing (free tier available)\n\n**3. Enable APIs**\n- Go to \"APIs \u0026 Services\" \u003e \"Library\"\n- Search and enable \"Google Sheets API\"\n- Search and enable \"Google Drive API\"\n\n**4. Configure OAuth Consent Screen**\n- Go to: [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent)\n- User Type: **External**\n- App name: sheet-cmd (or any name)\n- User support email: your email\n- Developer contact: your email\n- Click \"SAVE AND CONTINUE\"\n\n**5. Add Scopes**\n- Go to: [Add scopes](https://console.cloud.google.com/auth/scopes)\n- Click \"ADD OR REMOVE SCOPES\"\n- Search and add:\n  - `.../auth/spreadsheets`\n  - `.../auth/drive.readonly`\n- Click \"UPDATE\" then \"SAVE AND CONTINUE\"\n\n**6. Add Test Users**\n- Go to: [Add test users](https://console.cloud.google.com/auth/audience)\n- Click \"ADD USERS\"\n- Add your email address\n- Click \"SAVE AND CONTINUE\"\n\n**7. Create OAuth 2.0 Client ID**\n- Go to: [Credentials](https://console.cloud.google.com/apis/credentials)\n- Click \"CREATE CREDENTIALS\" \u003e \"OAuth client ID\"\n- Application type: **Desktop app**\n- Name: sheet-cmd\n- Click \"CREATE\"\n- **Copy the Client ID and Client Secret**\n\n**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.\n\n\u003c/details\u003e\n\n## :bulb: Usage\n\nAll commands use the **active account**, **active spreadsheet**, and **active sheet** by default. Set once, use everywhere.\n\n\u003c!-- BEGIN:COMMANDS --\u003e\n### Account Commands\n\n**add** - Add a Google account via OAuth\n\n```bash\nsheet-cmd account add\n```\n\n**list** - List all configured Google accounts\n\n```bash\nsheet-cmd account list\n```\n\n**select** - Select active Google account\n\n```bash\nsheet-cmd account select\n```\n\n**remove** - Remove a Google account\n\n```bash\nsheet-cmd account remove\n```\n\n**reauth** - Re-authenticate the active account\n\n```bash\nsheet-cmd account reauth\n```\n\n### Spreadsheet Commands\n\n**add** - Add a new spreadsheet (interactive by default, use --id for manual)\n\n```bash\nsheet-cmd spreadsheet add\n```\n\n**list** - List all configured spreadsheets\n\n```bash\nsheet-cmd spreadsheet list\n```\n\n**select** - Select a different spreadsheet (sets as active)\n\n```bash\nsheet-cmd spreadsheet select\n```\n\n**active** - Show the currently active spreadsheet\n\n```bash\nsheet-cmd spreadsheet active\n```\n\n**remove** - Remove a spreadsheet configuration\n\n```bash\nsheet-cmd spreadsheet remove\n```\n\n### Sheet Commands\n\n**list** - List all sheets in a spreadsheet\n\n```bash\nsheet-cmd sheet list\n```\n\n**select** - Select a sheet (sets as active)\n\n```bash\nsheet-cmd sheet select\n```\n\n**read** - Read the complete content of a sheet\n\n```bash\nsheet-cmd sheet read -n \"Sheet1\"\nsheet-cmd sheet read -n \"Sheet1\" -o markdown\nsheet-cmd sheet read -n \"Sheet1\" -r \"A1:B10\"\nsheet-cmd sheet read -n \"Sheet1\" -e output.csv\n```\n\n**add** - Add a new sheet to the spreadsheet\n\n```bash\nsheet-cmd sheet add -n \"NewSheet\"\n```\n\n**remove** - Remove a sheet from the spreadsheet\n\n```bash\nsheet-cmd sheet remove -n \"OldSheet\"\n```\n\n**rename** - Rename a sheet in the spreadsheet\n\n```bash\nsheet-cmd sheet rename -n \"OldName\" --new-name \"NewName\"\n```\n\n**copy** - Copy a sheet to a new sheet\n\n```bash\nsheet-cmd sheet copy -n \"Sheet1\" --to \"Sheet1 Copy\"\n```\n\n**write** - Write to a specific cell or range of cells\n\n```bash\nsheet-cmd sheet write -n \"Sheet1\" -c A1 -v \"Hello\"\nsheet-cmd sheet write -n \"Sheet1\" -r A1:B2 -v \"v1,v2;v3,v4\"\nsheet-cmd sheet write -n \"Sheet1\" -r A1:B2 -v \"v1,v2;v3,v4\" --no-preserve\n```\n\n**append** - Append a new row to the end of the sheet\n\n```bash\nsheet-cmd sheet append -n \"Sheet1\" -v \"val1,val2,val3\"\n```\n\n**import** - Import CSV file to a sheet\n\n```bash\nsheet-cmd sheet import -n \"Sheet1\" -f data.csv\nsheet-cmd sheet import -n \"Sheet1\" -f data.csv --skip-header\n```\n\n**export** - Export sheet data to JSON or CSV format\n\n```bash\nsheet-cmd sheet export -n \"Sheet1\" -f json -o output.json\nsheet-cmd sheet export -n \"Sheet1\" -f csv -o output.csv\n```\n\n**row-add** - Add a row to the sheet\n\n```bash\nsheet-cmd sheet row-add -r 5 --above\nsheet-cmd sheet row-add -r 5 --below --formulas\nsheet-cmd sheet row-add -r 5 --below --formulas --count 3\n```\n\n**row-remove** - Remove a row from the sheet\n\n```bash\nsheet-cmd sheet row-remove -r 5\nsheet-cmd sheet row-remove -r 5 --count 3\nsheet-cmd sheet row-remove -r 10 --above --count 5\n```\n\n### Update\n\nUpdate sheet-cmd to latest version\n\n```bash\nsheet-cmd update\n```\n\n### Completion Commands\n\n**install** - Install shell completion for your current shell\n\n```bash\nsheet-cmd completion install\n```\n\n\n\u003c!-- END:COMMANDS --\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAccount Management\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Add Google account via OAuth\nsheet-cmd account add\n\n# List all accounts (* = active)\nsheet-cmd account list\n\n# Select active account (interactive)\nsheet-cmd account select\n\n# Remove account (interactive)\nsheet-cmd account remove\n\n# Re-authenticate active account\nsheet-cmd account reauth\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSpreadsheet Management\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Add spreadsheet (interactive - browse Google Drive)\nsheet-cmd spreadsheet add\n\n# Add spreadsheet manually by ID\nsheet-cmd spreadsheet add --id \"1ABC...\"\n\n# List all spreadsheets (* = active)\nsheet-cmd spreadsheet list\n\n# Select active spreadsheet (interactive)\nsheet-cmd spreadsheet select\n\n# Select spreadsheet by ID\nsheet-cmd spreadsheet select --id \"1ABC...\"\n\n# Show currently active spreadsheet\nsheet-cmd spreadsheet active\n\n# Remove spreadsheet (interactive)\nsheet-cmd spreadsheet remove\n\n# Remove spreadsheet by ID\nsheet-cmd spreadsheet remove --id \"1ABC...\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSheet Management\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# List all sheets in spreadsheet\nsheet-cmd sheet list\n\n# Select active sheet (interactive)\nsheet-cmd sheet select\n\n# Select sheet by name\nsheet-cmd sheet select --name \"Sheet1\"\n\n# Add a new sheet\nsheet-cmd sheet add --name \"NewSheet\"\n\n# Remove a sheet (uses active if --name not provided)\nsheet-cmd sheet remove\nsheet-cmd sheet remove --name \"OldSheet\"\n\n# Rename a sheet (uses active if --name not provided)\nsheet-cmd sheet rename --new-name \"NewName\"\nsheet-cmd sheet rename --name \"OldName\" --new-name \"NewName\"\n\n# Copy a sheet (uses active if --name not provided)\nsheet-cmd sheet copy --to \"Sheet1 Copy\"\nsheet-cmd sheet copy --name \"Sheet1\" --to \"Sheet1 Copy\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eData Operations\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Read sheet content (uses active sheet if --name not provided)\nsheet-cmd sheet read\nsheet-cmd sheet read --name \"Sheet1\"\nsheet-cmd sheet read --output csv\nsheet-cmd sheet read --formulas\nsheet-cmd sheet read --export output.md\n\n# Write to single cell (uses active sheet if --name not provided)\nsheet-cmd sheet write --cell A1 --value \"Hello\"\nsheet-cmd sheet write --name \"Sheet1\" --cell A1 --value \"Hello\"\n\n# Write to range (uses active sheet if --name not provided)\nsheet-cmd sheet write --range A1:B2 --value \"v1,v2;v3,v4\"\nsheet-cmd sheet write --name \"Sheet1\" --range A1:B2 --value \"v1,v2;v3,v4\"\n\n# Append row (uses active sheet if --name not provided)\nsheet-cmd sheet append --value \"col1,col2,col3\"\nsheet-cmd sheet append --name \"Sheet1\" --value \"col1,col2,col3\"\n```\n\n**Note**: For `write` command, use `,` to separate columns and `;` to separate rows\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eImport/Export\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Import CSV (uses active sheet if --name not provided)\nsheet-cmd sheet import --file data.csv\nsheet-cmd sheet import --name \"Sheet1\" --file data.csv\nsheet-cmd sheet import --file data.csv --skip-header\n\n# Export to JSON (uses active sheet if --name not provided)\nsheet-cmd sheet export --format json --output output.json\nsheet-cmd sheet export --name \"Sheet1\" --format json --output output.json\n\n# Export to CSV (uses active sheet if --name not provided)\nsheet-cmd sheet export --format csv --output output.csv\nsheet-cmd sheet export --name \"Sheet1\" --format csv --output output.csv\n\n# Export specific range\nsheet-cmd sheet export --range B2:I25 --format csv --output output.csv\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSystem Commands\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Update to latest version\nsheet-cmd update\n\n# Install shell completion (bash/zsh)\nsheet-cmd completion install\n```\n\n\u003c/details\u003e\n\n## :package: Additional Information\n\n**Prerequisites:** Node.js 18+, Google Account, Linux/macOS/Windows\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eConfiguration Files\u003c/b\u003e\u003c/summary\u003e\n\nConfiguration files are stored in:\n- **Linux/WSL**: `~/.config/sheet-cmd/`\n- **macOS**: `~/Library/Preferences/sheet-cmd/`\n- **Windows**: `%APPDATA%/sheet-cmd/`\n\n**Files:**\n- `user_metadata.json` - Stores accounts, active selections, and spreadsheets\n- `config.json` - Stores general settings\n\n**Example structure:**\n```json\n{\n  \"config_path\": \"~/.config/sheet-cmd/config.json\",\n  \"activeAccount\": \"user@gmail.com\",\n  \"accounts\": {\n    \"user@gmail.com\": {\n      \"email\": \"user@gmail.com\",\n      \"oauth\": {\n        \"client_id\": \"xxx.apps.googleusercontent.com\",\n        \"client_secret\": \"xxx\",\n        \"refresh_token\": \"xxx\",\n        \"access_token\": \"xxx\",\n        \"expiry_date\": 1234567890\n      },\n      \"activeSpreadsheet\": \"my-budget\",\n      \"spreadsheets\": {\n        \"my-budget\": {\n          \"spreadsheet_id\": \"1ABC...\",\n          \"activeSheet\": \"monthly\"\n        }\n      }\n    }\n  }\n}\n```\n\n**Security**: All OAuth tokens are stored locally and automatically refreshed before expiry.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLLM Integration\u003c/b\u003e\u003c/summary\u003e\n\nSheet 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.\n\n**Why this matters:**\n- Simple command structure that LLMs can easily understand\n- Active context system reduces command complexity\n- Clear output formats (markdown, CSV, JSON)\n- OAuth 2.0 means no service account credentials to manage\n- Multi-account support for different contexts\n\n**Example Claude Code workflow:**\n```bash\n# Claude can read your budget spreadsheet\nsheet-cmd sheet read --name \"Budget\" --output markdown\n\n# Process the data and write results back\nsheet-cmd sheet write --name \"Analysis\" --cell A1 --value \"Summary\"\n\n# Export for further analysis\nsheet-cmd sheet export --name \"Data\" --format json --output data.json\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eUninstallation\u003c/b\u003e\u003c/summary\u003e\n\nTo completely remove sheet-cmd:\n\n```bash\n# 1. Remove shell completions (if installed)\nsheet-cmd completion uninstall\n\n# 2. Uninstall the package\nnpm uninstall -g sheet-cmd\n\n# 3. (Optional) Remove configuration files\n# Linux/WSL: rm -rf ~/.config/sheet-cmd/\n# macOS: rm -rf ~/Library/Preferences/sheet-cmd/\n# Windows: Remove %APPDATA%/sheet-cmd/\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDevelopment setup\u003c/b\u003e\u003c/summary\u003e\n\nFor local development:\n\n```bash\n# Clone repository\ngit clone https://github.com/lucasvtiradentes/sheet-cmd.git\ncd sheet-cmd\n\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run in development\nnpm run dev -- sheet list\n\n# Run tests\nnpm run test\nnpm run test:e2e\n\n# Type checking\nnpm run typecheck\n\n# Linting\nnpm run lint\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003ca target=\"_blank\" href=\"https://www.linkedin.com/in/lucasvtiradentes/\"\u003e\u003cimg src=\"https://img.shields.io/badge/-linkedin-blue?logo=Linkedin\u0026logoColor=white\" alt=\"LinkedIn\"\u003e\u003c/a\u003e\n    \u003ca target=\"_blank\" href=\"mailto:lucasvtiradentes@gmail.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/gmail-red?logo=gmail\u0026logoColor=white\" alt=\"Gmail\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003eMade with ❤️ by \u003cb\u003eLucas Vieira\u003c/b\u003e\u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasvtiradentes%2Fsheet-cmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucasvtiradentes%2Fsheet-cmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasvtiradentes%2Fsheet-cmd/lists"}