@11x.agency/gworkspace

Google Workspace CLI — Drive, Docs, Sheets from the terminal.

Auth once, use everywhere. JSON output by default, human-readable with --pretty. Works with both My Drive and Shared Drives.

Install

npm i -g @11x.agency/gworkspace

Or run without installing:

npx @11x.agency/gworkspace --help

Authentication

Quick start

gw auth

This opens your browser for Google sign-in. Tokens are stored at ~/.11x/gworkspace/token.json.

Check status

gw auth --status

Log out

gw logout

Custom OAuth credentials

Set environment variables or add a .env file to use your own Google Cloud OAuth app:

export GOOGLE_CLIENT_ID="your-client-id"
export GOOGLE_CLIENT_SECRET="your-client-secret"

Also supports GW_CLIENT_ID / GW_CLIENT_SECRET as aliases.

Commands

Drive

# List files in root
gw drive ls

# List files in a folder by path
gw drive ls /Projects

# List by folder ID
gw drive ls --folder <id>

# Filter by type
gw drive ls --type doc
gw drive ls --type sheet
gw drive ls --type folder

# Limit results
gw drive ls --limit 50

# Create a folder
gw drive mkdir "New Folder"
gw drive mkdir "Subfolder" --folder <parent-id>

# Search
gw drive search "quarterly report"
gw drive search "budget" --type sheet

# Upload
gw drive upload ./report.pdf
gw drive upload ./data.csv --folder <folder-id> --name "Q4 Data"

Shared Drives

All commands work with Shared Drives via the global --drive flag:

# List available Shared Drives
gw drive shared

# List files in a Shared Drive
gw --drive <shared-drive-id> drive ls
gw --drive <shared-drive-id> drive ls /Projects --pretty

# Create a folder in a Shared Drive
gw --drive <shared-drive-id> drive mkdir "New Folder"

# Search within a Shared Drive
gw --drive <shared-drive-id> drive search "report"

# Upload to a Shared Drive
gw --drive <shared-drive-id> drive upload ./file.pdf

# Create docs/sheets in a Shared Drive folder
gw doc create "Meeting Notes" --folder <shared-drive-folder-id>
gw sheet create "Budget" --folder <shared-drive-folder-id>

Docs

# Read document as plain text
gw doc read <id-or-url>

# Read as markdown
gw doc read <id-or-url> --markdown

# Create a new doc
gw doc create "Meeting Notes"
gw doc create "Project Brief" --folder <folder-id>

# Append text
gw doc append <id-or-url> "New paragraph here"
gw doc append <id-or-url> --file ./notes.txt

Sheets

# Read entire first sheet
gw sheet read <id-or-url>

# Read specific range
gw sheet read <id-or-url> "Sheet1!A1:C10"

# Write data (JSON)
gw sheet write <id-or-url> "A1:B2" '[["Name","Score"],["Alice","95"]]'

# Write from CSV
gw sheet write <id-or-url> "A1" --file ./data.csv

# Append rows
gw sheet append <id-or-url> '[["Bob","88"],["Carol","92"]]'
gw sheet append <id-or-url> --file ./more-data.csv

# Create spreadsheet
gw sheet create "Budget 2026"
gw sheet create "Sales Data" --folder <folder-id>

# List tabs
gw sheet list <id-or-url>

Output Modes

All commands support three output modes:

gw drive ls                # JSON (default) — for piping and scripting
gw drive ls --pretty       # Human-readable table
gw drive ls --quiet        # IDs only, one per line

URLs and IDs

All commands accept either a Google URL or a raw file ID:

gw doc read https://docs.google.com/document/d/1abc.../edit
gw doc read 1abc...

Error Handling

Errors go to stderr with exit code 1. Normal output goes to stdout, so piping works cleanly:

gw drive ls --quiet | head -5    # First 5 file IDs
gw sheet read <id> | jq '.[0]'  # First row as JSON

Development

git clone https://github.com/robinfaraj/gworkspace-cli.git
cd gworkspace-cli
pnpm install
pnpm build
node dist/index.js --help

To use your own OAuth credentials during development, create a .env file:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Build and verify (pnpm build && node dist/index.js --help)
5. Commit and push
6. Open a Pull Request

License

MIT — see LICENSE.