🎺 Overview

gsheet is a CLI and Node.js library for managing Google Sheets from the terminal or from scripts.

❓ Motivation

Google Sheets is often the easiest place to store operational data, but the browser workflow is slow for repeated reads, writes, imports, exports, and AI-agent automation. gsheet keeps account, spreadsheet, and sheet context locally so commands and scripts can work with short, repeatable calls.

⭐ Features

• Multi-account support for personal, work, and other Google accounts
• OAuth 2.0 login without service accounts
• Interactive Google Drive spreadsheet selection
• Active account, spreadsheet, and sheet context
• Read, write, append, import, and export workflows
• Markdown, CSV, and JSON output for CLI and AI-agent usage

🚀 Quick Start

1. Install the CLI globally:

   npm i -g gsheet-lvt
   # now you can use "gs" or "gsheet"

2. Add a Google account:

   gs account add

3. Add and select a spreadsheet:

   gs spreadsheet add
   gs sheet select

4. Read the active sheet:

   gs sheet read

🧰 Commands

# account commands
gs account add
gs account list
gs account select [email]
gs account remove [email]
gs account reauth

# spreadsheet commands
gs spreadsheet add [--id <value>] [--name <value>]
gs spreadsheet create --name <value> [--local-name <value>] [--no-select]
gs spreadsheet list [--output <value>]
gs spreadsheet remove [--id <value>]
gs spreadsheet select [--id <value>] [--add] [--name <value>]
gs spreadsheet active [--output <value>]

# sheet commands
gs sheet list [--output <value>]
gs sheet active [--output <value>]
gs sheet select [--name <value>]
gs sheet read [--name <value>] [--output <value>] [--formulas] [--export <value>] [--range <value>]
gs sheet add --name <value>
gs sheet remove [--name <value>]
gs sheet rename [--name <value>] --new-name <value>
gs sheet copy [--name <value>] --to <value>
gs sheet write [--name <value>] [--cell <value>] [--initial-cell <value>] [--range <value>] [--value <value>] [--value-file <value>] [--no-infer-types] [--no-preserve]
gs sheet append [--name <value>] --value <value> [--no-infer-types]
gs sheet import [--name <value>] --file <value> [--initial-cell <value>] [--skip-header] [--no-infer-types]
gs sheet export [--name <value>] [--range <value>] --format <value> [--output <value>]
gs sheet row-add --row <value> [--name <value>] [--above] [--below] [--formulas] [--count <value>]
gs sheet row-remove --row <value> [--name <value>] [--above] [--below] [--count <value>]

gs update

# completion commands
gs completion zsh
gs completion bash
gs completion fish

🧩 Completion

Add completion to your shell config so gs <tab> can show available commands, subcommands, and flags.

eval "$(gs completion zsh)"

Use command -v gs >/dev/null 2>&1 && eval "$(gs completion zsh)" instead if this shell config is shared with machines where gs may not be installed.

For the interactive completion menu shown while typing, install the zsh-autocomplete project. Bash and Fish completion scripts are also available:

gs completion bash
gs completion fish

🛠️ Development

Install the development binaries when you want local code changes to be available from any terminal. This creates gsheetd and gsd, which run the current workspace version:

pnpm dev:install
gsheetd --help
gsd --help

For development autocomplete, follow the Completion section and use the dev binary in your shell config:

command -v gsd >/dev/null 2>&1 && eval "$(gsd completion zsh)"

Remove the development binaries when you no longer need them:

pnpm dev:uninstall

⚙️ Configuration

Configuration is stored locally under the app config directory for your OS:

• Linux/WSL: ~/.config/gsheet/
• macOS: ~/Library/Preferences/gsheet/
• Windows: %APPDATA%/gsheet/

OAuth tokens are stored locally and refreshed automatically before expiry.

{
  "config_path": "~/.config/gsheet/config.json",
  "user_metadata_path": "~/.config/gsheet/user_metadata.json",
  "activeAccount": "[email protected]",
  "activeSpreadsheet": "my-budget",
  "activeSheet": "monthly"
}

📜 License

MIT