Google Workspace CLI (`gws`) Comprehensive Guide

#google-workspace#cli#mcp#agents

Google Workspace CLI (gws) Comprehensive Guide The Google Workspace CLI (gws) is a powerful, dynamically built command-line tool that provides access to the com

Google Workspace CLI (gws) Comprehensive Guide The Google Workspace CLI (gws) is a powerful, dynamically built command-line tool that provides access to the complete surface area of Google APIs (Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, etc.) without writing manual cURL commands or maintaining custom REST scripts. Every response is structured JSON, making it an ideal companion for both human developers and AI Agents. 🚀 1. Installation The CLI provides pre-built native binaries, so a full compiler toolchain isn't required. Using npm (Recommended) You can install gws via npm (requires Node.js 18+): From Source (Cargo) If you prefer building from source, use standard Rust tooling: 🔐 2. Authentication Workflows The gws CLI supports multiple authentication methods depending on your environment (local laptop, CI/CD pipeline, or server). A. Interactive Local Desktop (The "Easy" Way) If you are running the CLI on your personal machine with a browser available: 1. Initial Setup: Creates a Google Cloud Project, enables APIs, and initiates login. This requires the gcloud CLI to be installed. 1. Subsequent Logins: If you need to refresh scopes or change accounts: (Note: Credentials are encrypted at rest using AES-256-GCM and stored in your OS keyring). B. Headless / CI (Export Flow) For environments without browsers (like GitHub Actions or remote VPS): 1. Complete interactive auth on your laptop. 2. Export the credential payload: 1. Load it on the headless machine: C. Service Account (Server-to-Server) If you are building backend automation acting on behalf of an enterprise domain: 🛠️ 3. Common Usage Patterns & Syntax Because gws is dynamically built from Google's Discovery Service, it usually follows the pattern: gws <service <resource <method. Google Drive List the 10 most recent files: Upload a local file (Multipart Upload): Stream paginated results directly to jq: Google Sheets CRITICAL: Google Sheets uses ! in range definitions (e.g., Sheet1!A1), whic