@googleworkspace/cli

What is googleworkspace-cli?

googleworkspace/cli (published as @googleworkspace/cli) is a command-line tool for Google Workspace. It lets you work with multiple Workspace APIs—such as Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more—using a single CLI.

The command surface is built dynamically at runtime from Google’s Discovery Service, rather than shipping a fixed list of commands. The project is also described as including “AI agent skills,” and the CLI emphasizes structured JSON output for automation.

Key Features

• Single CLI for multiple Workspace services: Provides one interface to interact with Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and other Workspace APIs.
• Dynamic command generation from Discovery Service: Commands and methods are built by reading Google’s own Discovery Service at runtime, so new endpoints/methods can be picked up without a static command list.
• Structured JSON output: Designed for use with automation and AI agents; responses are returned in structured JSON.
• Schema introspection for API methods: Use gws schema <...> to inspect the request/response schema for a method.
• Request simulation and pagination helpers: Use --dry-run to preview requests and --page-all to stream paginated results (optionally to tools like jq).
• Multiple authentication workflows: Supports setup/login workflows suitable for local use, CI, and servers, including integration with gcloud when available.
• Bundled agent skills: The repository documentation notes that it includes “40+ agent skills.”

How to Use googleworkspace-cli

1. Install the CLI:
   • Via npm: npm install -g @googleworkspace/cli
   • Or using a pre-built binary from GitHub Releases
   • Or build from source: cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux also mention Homebrew; Nix flake is available.)
2. Authenticate (one-time project setup, then login):
   • gws auth setup (requires gcloud installed and authenticated)
   • gws auth login (subsequent OAuth login)
   • For manual token-based or console-based flows, the docs list environment variables and a manual OAuth setup path.
3. Run commands against a resource. Example workflows from the docs include:
   • List files: gws drive files list --params '{"pageSize": 5}'
   • Create a spreadsheet: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Send a Chat message: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • Introspect schema: gws schema drive.files.list

Use Cases

• Automate Drive workflows with pagination and JSON: Stream large result sets from Drive list endpoints and process them using downstream tools (e.g., by combining --page-all output with jq).
• Send Gmail/Chat/Calendar requests without writing raw REST calls: Use the CLI’s resource-focused commands to create or update objects while relying on the generated interface.
• Validate request structure before executing: Use --dry-run to preview what the CLI would send, which can help when generating payloads for Sheets, Chat, and other resources.
• Build AI agent tooling around Workspace APIs: Use structured JSON responses and the included agent skills so an LLM-driven agent can decide which Workspace actions to call with less custom glue.
• Discover how to call an API method from the CLI: When you know a method exists but not the exact request shape, use gws schema <method> to inspect the request/response schema.

FAQ

• Is googleworkspace-cli an official Google product? No. The repository notes: “This is not an officially supported Google product.”

• Does it have a fixed list of commands? No. The docs state that it does not ship a static list of commands; it reads Google’s Discovery Service at runtime and builds its command surface dynamically.

• What do I need to install and run it? The prerequisites list Node.js 18+ for the npm installation flow. Authentication requires a Google Cloud project for OAuth credentials and a Google account with Workspace access.

• Which authentication setup should I use? The docs describe multiple paths:

  • gcloud-assisted setup (gws auth setup) when you have gcloud installed and authenticated
  • manual OAuth setup via Google Cloud Console when automation isn’t possible
  • token-based/manual credentials via environment variables (as documented)

• Are there scope-related limitations during development/testing? Yes. The docs warn that if the OAuth app is unverified (testing mode), Google limits consent to ~25 scopes and that the recommended scope preset (85+ scopes) will fail for unverified apps—especially for @gmail.com accounts.

Alternatives

• Direct REST API calls with curl or an HTTP client: Lets you call Workspace endpoints directly, but you must manage request formatting, pagination, and authentication details yourself.
• Official SDKs for specific Workspace services (e.g., language-specific Google APIs libraries): Provide typed client methods for particular services, but typically separate code paths per API rather than one dynamically generated CLI interface.
• Other CLI tools for Google APIs: Alternative CLIs may focus on specific services or use static command sets; depending on the tool, they may not offer the same dynamic Discovery Service-driven command generation or structured JSON + schema introspection workflow described here.