The gws command-line interface provides a unified tool for interacting with all Google Workspace APIs, including Drive, Gmail, and Calendar. Designed for both human users and AI agents, it eliminates boilerplate and produces structured JSON output. This project is not an officially supported Google product and is under active development.

The core methodology of gws is its dynamic command surface generation. Unlike traditional CLIs with static command lists, gws reads Google's own Discovery Service at runtime. When a Google Workspace API endpoint or method is added, gws automatically incorporates it. This dynamic behavior is implemented via a two-phase parsing strategy:

1. The CLI first parses argv[1] to identify the target service (e.g., drive).
2. It then fetches the corresponding Discovery Document for that service (cached for 24 hours to optimize performance).
3. Using the Discovery Document, gws dynamically constructs a command tree using clap::Command, mapping the document's resources and methods to CLI commands.
4. The remaining command-line arguments are then re-parsed against this newly built, dynamic command structure.
5. Finally, it handles authentication, builds the HTTP request based on the parsed command and arguments, and executes the API call. All output, including success messages, errors, and download metadata, is consistently provided in structured JSON format.

Prerequisites for gws include Node.js 18+ (for npm installation), a Google Cloud project for OAuth credentials, and a Google account with Workspace access. Installation is typically done via npm install -g @googleworkspace/cli, which bundles pre-built native binaries, removing the need for a Rust toolchain. Alternatively, users can build from source using cargo install or leverage a Nix flake.

gws enhances usability for humans by offering built-in --help for every resource, --dry-run to preview requests, and auto-pagination. For AI agents, its structured JSON responses and bundled agent skills enable large language models (LLMs) to manage Workspace functionalities without needing custom integrations. Examples include listing Drive files (gws drive files list --params '{"pageSize": 10}'), creating Sheets spreadsheets (gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'), and sending Chat messages (gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}' --dry-run). The $gws schema <service.method>$ command allows introspection of any method's request/response schema.

Authentication supports multiple workflows:

• Interactive (local desktop): gws auth setup automates Google Cloud project configuration (creating a project, enabling APIs), followed by gws auth login for OAuth consent. Credentials are encrypted at rest using the OS keyring.
• Manual OAuth setup: For explicit control or when gws auth setup is not feasible, users configure OAuth consent and credentials in the Google Cloud Console, downloading a client JSON file to ~/.config/gws/client_secret.json. Test users must be added for unverified apps.
• Headless / CI: Interactive authentication can be performed on a machine with a browser, and credentials then exported via gws auth export --unmasked > credentials.json to be used on headless machines by setting the GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE environment variable.
• Service Account: Pointing to a service account key file via GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE enables server-to-server authentication.
• Pre-obtained Access Token: An existing OAuth2 access token can be supplied via the GOOGLE_WORKSPACE_CLI_TOKEN environment variable, which takes the highest precedence. Environment variables can also be loaded from a .env file.

gws deeply integrates with AI agent ecosystems, providing over 100 Agent Skills (defined in SKILL.md files) covering all supported APIs, common workflows, and curated recipes for various Workspace services. These skills can be installed using $npx skills add <repo_url>$ for frameworks like OpenClaw, allowing agents to automatically discover and utilize gws capabilities. A gws-shared skill includes an install block to auto-install the CLI if not found. Furthermore, a Gemini CLI Extension allows direct access to all gws commands and skills from the Gemini CLI by running gemini extensions install https://github.com/googleworkspace/cli, leveraging gws's secure authentication.

Advanced usage features include:

• Multipart Uploads: Supported for operations like gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf.
• Pagination: Commands support --page-all (NDJSON output), --page-limit <N>, and --page-delay <MS>.
• Shell Escaping: Sheets ranges (e.g., Sheet1!A1:C10) require single quotes to prevent bash history expansion.
• Model Armor (Response Sanitization): Integration with Google Cloud Model Armor allows scanning API responses for prompt injection before reaching an agent. This can be enabled with --sanitize "projects/P/locations/L/templates/T" or configured globally via GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE and GOOGLE_WORKSPACE_CLI_SANITIZE_MODE (warn/block).

Common troubleshooting scenarios include "Access blocked" or 403 errors (due to unverified OAuth app in testing mode or missing test users), "Google hasn't verified this app" warnings (expected in testing mode), "Too many scopes" errors for unverified apps exceeding ~25 OAuth scopes (fixed by selecting fewer scopes), gcloud CLI not found warnings (addressed by installing gcloud or using manual OAuth setup), redirect_uri_mismatch (fixed by ensuring the OAuth client is a "Desktop app" type), and "API not enabled" errors (accessNotConfigured, resolved by enabling the specific API in the Google Cloud Console via the provided enable_url).

For development, the project uses Rust, with standard commands for building (cargo build), linting (cargo clippy), and testing (cargo test). An HTML coverage report can be generated via ./scripts/coverage.sh. The project is licensed under Apache-2.0.