cli

Generates the entire CLI command surface at runtime by fetching Google's Discovery Service JSON schemas and parsing them into executable commands. Unlike static CLI tools with hardcoded commands, gws reads Discovery Documents for each API (Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin) and builds command trees dynamically, ensuring new Google API endpoints are automatically available without code changes or releases. Uses a two-phase parsing strategy: first clap parses static global flags, then Discovery Document schemas are loaded to build method-specific argument parsers.

Ensures all API responses are returned as structured JSON by default, with optional format conversion to YAML, CSV, or human-readable tables via --format flag. Every gws command returns machine-parseable output suitable for piping to jq, agents, or downstream systems. Implements format negotiation at the response serialization layer, allowing consumers to choose their preferred output representation without re-invoking the API.

Implements a custom HTTP client layer that executes authenticated requests to Google APIs with built-in retry logic, exponential backoff, and error handling. The client manages request marshaling (JSON serialization), response parsing, and error classification (retryable vs. fatal). Handles rate limiting (429 responses) and transient failures (5xx errors) transparently, improving reliability for long-running workflows.

Provides unified CLI access to all major Google Workspace APIs (Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin) through a single command interface. Each API is discovered dynamically from Google's Discovery Service, ensuring feature parity with the latest API versions. Supports all resource types and methods for each service, from file operations in Drive to message management in Gmail to spreadsheet operations in Sheets.

Returns paginated results as newline-delimited JSON (NDJSON) where each line is a complete JSON object, enabling streaming processing without loading entire result sets into memory. NDJSON format is compatible with standard Unix tools (grep, sed, awk) and streaming JSON processors (jq, jstream). Particularly useful for large exports (100k+ records) where loading everything into memory would be infeasible.

Supports multiple authentication flows (interactive OAuth2, service account JSON, raw access tokens, CI environment exports) with automatic credential discovery and token refresh. Implements a credential manager that handles OAuth2 token lifecycle, service account key loading, and environment-based auth for CI/CD pipelines. Credentials are cached locally and refreshed transparently when expired, eliminating manual token management for long-running workflows.

Automatically fetches all paginated results from Google Workspace APIs using the --page-all flag, returning results as newline-delimited JSON (NDJSON) for memory-efficient streaming. Implements pagination logic at the HTTP client layer, transparently following next-page tokens and aggregating results without requiring manual pagination loops. Supports both list operations and streaming output for large result sets.

Provides 40+ pre-built agent skills (documented in SKILL.md files) that encapsulate common Workspace operations for AI agents and LLM workflows. Skills are high-level abstractions over raw API calls (e.g., +append for appending to Sheets, +upload for Drive file uploads, +send for Gmail messages, +read for document content extraction). Designed for OpenClaw and Gemini CLI extensions, allowing LLMs to invoke complex multi-step operations as single commands.

Provides high-level service helpers (+append, +upload, +send, +read) that encapsulate common patterns across Google Workspace services without requiring deep API knowledge. Helpers are implemented as convenience wrappers over raw API calls, handling parameter marshaling, error handling, and response formatting. For example, +upload abstracts Drive file creation with multipart uploads, +append handles Sheets batch updates, +send manages Gmail message composition with attachments.

Integrates Google Cloud Model Armor via the --sanitize flag to filter sensitive data from API responses before returning them to users or agents. Sanitization removes PII (personally identifiable information), credentials, and other sensitive fields from structured responses, making them safe for logging, sharing, or passing to untrusted agents. Implemented at the response serialization layer, operating on the JSON response before output formatting.

Supports flexible parameter passing via --params (JSON object), --json (raw JSON file), and inline flag syntax for API method arguments. Parameters are validated against Discovery Document schemas before sending to Google APIs, ensuring type correctness and required field presence. Supports nested objects and arrays, allowing complex request bodies to be specified from the command line or files.

Implements a two-phase parsing strategy that bridges static CLI argument parsing (clap) with dynamic Discovery Document schemas. Phase 1 parses global flags (--format, --sanitize, --page-all) using clap; Phase 2 loads the Discovery Document for the requested API and builds method-specific argument parsers dynamically. This allows gws to support arbitrary Google API methods without pre-compiling command definitions, while still providing early validation and help text.

Integrates with Google's Gemini CLI extension to expose gws commands and skills as tools available to Gemini LLM agents. The extension reads gws SKILL.md files and command definitions to build a tool registry that Gemini can invoke. Enables Gemini agents to autonomously perform Workspace tasks (send emails, create documents, manage calendars) by calling gws commands with natural language reasoning.