Google Workspace CLI

---

name: gworkspace-cli description: > Interact with Google Workspace (Drive, Docs, Sheets) via the gw CLI. Use when an agent needs to browse, read, create, search, or manage files in Google Drive, read or write Google Docs, or read/write Google Sheets — all from the terminal. Works with both My Drive and Shared Drives. required_binaries: - gw required_env: - name: GOOGLE_CLIENT_ID description: Google OAuth client ID (optional — embedded credentials used by default) required: false - name: GOOGLE_CLIENT_SECRET description: Google OAuth client secret (optional — embedded credentials used by default) required: false - name: GW_CLIENT_ID description: Alias for GOOGLE_CLIENT_ID required: false - name: GW_CLIENT_SECRET description: Alias for GOOGLE_CLIENT_SECRET required: false config_paths: - ~/.11x/gworkspace/token.json - ~/.11x/gworkspace/config.json install: npm i -g @11x.agency/gworkspace source: https://github.com/robinfaraj/gworkspace-cli

---

gworkspace-cli

Manage Google Drive, Docs, and Sheets from the terminal with gw.

Do This First

Ensure gw is installed: npm i -g @11x.agency/gworkspace

Ensure authenticated: run gw auth --status. If not authenticated, run gw auth.

If targeting a Shared Drive, get the drive ID first: gw drive shared

Authentication

gw auth                 # Opens browser for Google sign-in
gw auth --status        # Check current auth (email, scopes, expiry)
gw logout               # Remove stored credentials

Token stored at ~/.11x/gworkspace/token.json. OAuth credentials via env vars or .env file:

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

GW_CLIENT_ID / GW_CLIENT_SECRET (aliases)

Commands

Drive

# List files
gw drive ls                              # Root of My Drive
gw drive ls /Projects                    # By path
gw drive ls --folder                # By folder ID
gw drive ls --type doc                  # Filter: doc, sheet, folder, all
gw drive ls --limit 50                  # Pagination
Create folder
gw drive mkdir "Folder Name"
gw drive mkdir "Subfolder" --folder 
Search
gw drive search "quarterly report"
gw drive search "budget" --type sheet
Upload
gw drive upload ./file.pdf
gw drive upload ./data.csv --folder  --name "Q4 Data"
List Shared Drives
gw drive shared

Shared Drives

Use the global --drive flag before any subcommand:

gw --drive  drive ls
gw --drive  drive ls /Projects
gw --drive  drive mkdir "New Folder"
gw --drive  drive search "report"
gw --drive  drive upload ./file.pdf

To create docs/sheets in a Shared Drive, use --folder with a Shared Drive folder ID:

gw doc create "Title" --folder 
gw sheet create "Title" --folder 

Docs

gw doc read                     # Plain text output
gw doc read  --markdown         # Markdown output
gw doc create "Title"                   # Create empty doc, returns ID + URL
gw doc create "Title" --folder      # Create in specific folder
gw doc append  "text"           # Append text to end of doc
gw doc append  --file ./notes.txt  # Append from file

Sheets

gw sheet read                   # Read entire first sheet (JSON rows)
gw sheet read  "Sheet1!A1:C10"  # Read specific range
gw sheet write  "A1:B2" '[["Name","Score"],["Alice","95"]]'
gw sheet write  "A1" --file ./data.csv
gw sheet append  '[["Bob","88"]]'
gw sheet append  --file ./more.csv
gw sheet create "Title"                 # Create spreadsheet
gw sheet create "Title" --folder 
gw sheet list                   # List tabs/sheets

Output Modes

All commands support three output modes:

| Flag | Output | Use case | |------------|----------------------------|--------------------| | *(default)* | JSON | Piping, scripting | | --pretty | Human-readable table | Terminal viewing | | --quiet | IDs only, one per line | Chaining commands |

I/O Contract

stdout: Data output (JSON, table, or IDs)

stderr: Errors, status messages, progress

Exit 0: Success

Exit 1: Any error (auth, not found, permission, network)

URLs and IDs

All commands accept either format — paste a full Google URL or just the ID:

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

Error Messages

| Condition | Message | |------------------------|------------------------------------------------------------| | No token | Error: Not authenticated. Run 'gw auth' to get started. | | Token expired | Error: Session expired. Run 'gw auth' to re-authenticate. | | File not found | Error: File not found. | | Permission denied | Error: No access to this file. Make sure it's shared with your account. | | Network error | Error: Could not reach Google APIs. Check your connection. |

Common Agent Workflows

Browse a Shared Drive and read a doc

gw drive shared --quiet                          # Get drive IDs
gw --drive  drive ls --pretty                # Browse root
gw --drive  drive ls --folder     # Drill into folder
gw doc read                              # Read the doc

Create a doc with content in a specific folder

gw drive mkdir "Project X"                       # Create folder, get ID
gw doc create "Requirements" --folder        # Create doc, get ID
gw doc append  "# Requirements\n\n..."   # Write content

Export sheet data for processing

gw sheet read  --quiet > data.tsv            # Tab-separated to file
gw sheet read  "Sheet1!A1:D100" | jq '.'     # JSON for processing

Upload and organize files

gw drive mkdir "Reports" --folder 
gw drive upload ./q4-report.pdf --folder  --name "Q4 Report 2026"