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"