- name
- gworkspace-cli
- description
- >
- required_binaries
- required_env
- description
- Google OAuth client ID (optional — embedded credentials used by default)
- required
- false
- description
- Google OAuth client secret (optional — embedded credentials used by default)
- required
- false
- description
- Alias for GOOGLE_CLIENT_ID
- required
- false
- description
- Alias for GOOGLE_CLIENT_SECRET
- required
- false
- config_paths
- 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
gwis installed:npm i -g @11x.agency/gworkspace - Ensure authenticated: run
gw auth --status. If not authenticated, rungw 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 credentialsToken stored at ~/.11x/gworkspace/token.json. OAuth credentials via env vars or .env file:
GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRETGW_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 <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 sharedShared Drives
Use the global --drive <id> flag before any subcommand:
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.pdfTo create docs/sheets in a Shared Drive, use --folder with a Shared Drive folder ID:
gw doc create "Title" --folder <shared-drive-folder-id>
gw sheet create "Title" --folder <shared-drive-folder-id>Docs
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 fileSheets
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/sheetsOutput 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 <id> drive ls --pretty # Browse root
gw --drive <id> drive ls --folder <folder-id> # Drill into folder
gw doc read <doc-id> # Read the docCreate a doc with content in a specific folder
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\
\
..." # Write contentExport sheet data for processing
gw sheet read <id> --quiet > data.tsv # Tab-separated to file
gw sheet read <id> "Sheet1!A1:D100" | jq '.' # JSON for processingUpload and organize files
gw drive mkdir "Reports" --folder <parent-id>
gw drive upload ./q4-report.pdf --folder <new-folder-id> --name "Q4 Report 2026"