Google Workspace CLI

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.

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

bash

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

bash

# List files
gw drive ls                              # Root of My Drive
gw drive ls /Projects                    # By path
gw drive ls --folder <id>               # 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 <parent-id>

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

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

# List Shared Drives
gw drive shared

Shared Drives

Use the global --drive <id> flag before any subcommand:

bash

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

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

bash

gw doc create "Title" --folder <shared-drive-folder-id>
gw sheet create "Title" --folder <shared-drive-folder-id>

Docs

bash

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

Sheets

bash

gw sheet read <id|url>                  # Read entire first sheet (JSON rows)
gw sheet read <id|url> "Sheet1!A1:C10"  # Read specific range
gw sheet write <id|url> "A1:B2" '[["Name","Score"],["Alice","95"]]'
gw sheet write <id|url> "A1" --file ./data.csv
gw sheet append <id|url> '[["Bob","88"]]'
gw sheet append <id|url> --file ./more.csv
gw sheet create "Title"                 # Create spreadsheet
gw sheet create "Title" --folder <id>
gw sheet list <id|url>                  # 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:

bash

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

bash

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

Create a doc with content in a specific folder

bash

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

Export sheet data for processing

bash

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

Upload and organize files

bash

gw drive mkdir "Reports" --folder <parent-id>
gw drive upload ./q4-report.pdf --folder <new-folder-id> --name "Q4 Report 2026"