What are the prerequisites for using gws?

The prerequisites are: 1) Node.js 18 or higher (for npm installation), 2) A Google Cloud project for OAuth credentials, and 3) A Google account with access to Google Workspace. The Google Cloud project can be created via the Google Cloud Console, gcloud CLI, or the gws auth setup command.

How do I authenticate gws?

There are multiple authentication methods: 1) Interactive local desktop using 'gws auth setup' and 'gws auth login', 2) Manual OAuth setup through Google Cloud Console, 3) Browser-assisted auth for human or agent flows, 4) Headless/CI using exported credentials, 5) Service Account authentication, or 6) Pre-obtained Access Token. Credentials are encrypted at rest using AES-256-GCM.

What should I do if I get an 'Access blocked' or 403 error during login?

This typically occurs when your OAuth app is in testing mode and your account is not listed as a test user. To fix this, you need to: 1) Open the OAuth consent screen in your GCP project, 2) Go to 'Test users', 3) Click 'Add users', 4) Enter your Google account email, and then 5) Retry 'gws auth login'.

What are Helper Commands in gws and how do I use them?

Helper Commands are hand-crafted commands prefixed with '+' that provide additional functionality alongside auto-generated Discovery commands. Examples include '+send' for Gmail, '+append' for Sheets, '+upload' for Drive, and '+agenda' for Calendar. Time-aware helpers automatically use your Google account timezone. You can view available helpers by running 'gws <service> --help'.

How do I handle the 'Too many scopes' error during authentication?

This error occurs because unverified (testing mode) apps are limited to approximately 25 OAuth scopes. The 'recommended' scope preset exceeds this limit. To fix this, you should select only the specific scopes you need by using the command: 'gws auth login --scopes drive,gmail,calendar' (replacing with your required services).

Google Workspace CLI

WebsiteFreeAI Code Assistant AI API Design

Google Workspace CLI is a unified command-line tool that provides access to all Google Workspace services (Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin) through a single interface, with built-in AI agent skills and dynamic command generation.

웹사이트 방문

이 도구 광고하기

https://github.com/googleworkspace/cli?ref=producthunt

개요
동영상
대안

제품 정보

업데이트됨:Mar 16, 2026

Google Workspace CLI이란?

Google Workspace CLI (gws) is an open-source command-line interface that enables users to interact with all Google Workspace services directly from their terminal, eliminating the need for multiple browser tabs or custom API integrations. Built with Rust and distributed as a Node.js package, it offers a streamlined way to automate Workspace tasks through command-line operations. While not an officially supported Google product, it provides comprehensive access to Google Workspace APIs with features like OAuth authentication, structured JSON output, and built-in AI agent capabilities.

Google Workspace CLI의 주요 기능

Google Workspace CLI (gws) is a unified command-line tool that provides seamless access to all Google Workspace services including Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin. It dynamically builds its command surface from Google's Discovery Service, offers structured JSON output for AI agent integration, includes 100+ pre-built agent skills, and supports multiple authentication workflows. The tool simplifies automation and management of Google Workspace services through a single command-line interface, making it ideal for both human users and AI agents.

Dynamic Command Generation: Automatically builds commands from Google's Discovery Service, ensuring up-to-date access to all API endpoints without manual updates

AI Agent Integration: Includes 100+ pre-built agent skills and provides structured JSON output, making it easy for AI agents to interact with Google Workspace services

Flexible Authentication: Supports multiple authentication workflows including interactive desktop, browser-assisted, headless/CI, and service account authentication

Helper Commands: Provides hand-crafted helper commands (prefixed with '+') for common workflows across different services, simplifying complex operations

Google Workspace CLI의 사용 사례

Enterprise Automation: Automate routine tasks like email management, document creation, and calendar scheduling across an organization using scripts and AI agents

Development Integration: Integrate Google Workspace services into development workflows and CI/CD pipelines for automated testing and deployment

Personal Productivity: Streamline personal workflow management through command-line access to emails, calendar, and documents without switching between browser tabs

AI Assistant Development: Build AI assistants that can interact with Google Workspace services using structured JSON outputs and pre-built agent skills

장점

Unified interface for all Google Workspace services

Automatic updates through Discovery Service integration

Rich support for AI agent integration with structured outputs

단점

Project is still under active development with potential breaking changes

Requires technical knowledge to set up and use effectively

OAuth scope limitations for unverified apps in testing mode

Google Workspace CLI 사용 방법

Install Google Workspace CLI: Run 'npm install -g @googleworkspace/cli' in your terminal to install the CLI globally

Set up authentication: Run 'gws auth setup' which will walk you through creating a Google Cloud project and enabling necessary APIs. If you don't have gcloud CLI, you'll need to set up OAuth credentials manually in Google Cloud Console.

Log in to your Google account: Run 'gws auth login' to authenticate. This will open a browser window for you to sign in to your Google account and grant permissions.

Select required API scopes: During login, choose which Google Workspace APIs you need access to (e.g., 'gws auth login -s drive,gmail,sheets' for specific services)

Test the connection: Try a simple command like 'gws drive files list --params '{"pageSize": 5}'' to verify everything is working

Learn basic commands: Use helper commands prefixed with '+' for common tasks. For example: 'gws gmail +send' to send emails, 'gws drive +upload' for file uploads, 'gws calendar +agenda' to see upcoming events

Handle pagination: Use --page-all flag to auto-paginate results, --page-limit <N> to set max pages, and --page-delay <MS> to set delay between pages

Work with Google Sheets: Always use single quotes when specifying sheet ranges, e.g. 'gws sheets spreadsheets values get --params '{"spreadsheetId": "ID", "range": "Sheet1!A1:C10"}'

Enable debug logging (optional): Set GOOGLE_WORKSPACE_CLI_LOG environment variable for debug output, e.g. 'export GOOGLE_WORKSPACE_CLI_LOG=gws=debug'

Install AI agent skills (optional): Run 'npx skills add https://github.com/googleworkspace/cli' to install all agent skills, or install specific ones like 'npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive'

Google Workspace CLI 자주 묻는 질문

Google Workspace CLI (gws) is a command-line tool that provides unified access to all Google Workspace services including Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin. It dynamically builds its command surface from Google's Discovery Service and includes AI agent skills. It's designed for both human users and AI agents to interact with Google Workspace services.