Gws Setup

What Is Gws Setup?

Gws Setup is a specialized Claude Code skill designed to automate and streamline the initial setup and configuration of the Google Workspace CLI (gws). The skill provides end-to-end guidance for developers and administrators seeking to enable programmatic access to Google Workspace services—including Gmail, Drive, Calendar, Sheets, Docs, Chat, and Tasks—using the official CLI tool published by Google. By leveraging Gws Setup, users can confidently navigate the entire workflow: from installing prerequisites and provisioning OAuth credentials to authenticating the CLI and enabling over 90 agent skills tailored for Claude Code environments.

Why Use Gws Setup?

Setting up the Google Workspace CLI involves several intricate steps, each with its own prerequisites and potential pitfalls. Manual setup is error-prone and time-consuming, especially for those unfamiliar with Google Cloud Platform (GCP) project configurations, OAuth credential management, and the nuances of Google API authentication. Gws Setup addresses these challenges by offering:

• Step-by-step automation: The skill checks your environment, identifies missing prerequisites, and guides you through each step, reducing the chance of misconfiguration.
• Troubleshooting assistance: It can help diagnose and resolve common authentication issues, ensuring that the setup process is robust and repeatable.
• Skill installation: Beyond basic setup, Gws Setup enables a comprehensive set of agent skills for Claude Code, unlocking advanced automation and integration scenarios across Google Workspace services.
• Time savings: Streamlined processes mean less time spent on tedious setup and more time focused on development and automation tasks.

How to Get Started

Gws Setup is compatible with Claude Code environments. Before beginning, ensure you meet the following prerequisites:

• Node.js 18 or later is installed on your system.
• You have a Google account (either personal or Workspace).
• You have access to the Google Cloud Console (https://console.cloud.google.com).

Follow these steps to perform a first-time setup:

1. Pre-flight

Checks

Before making any changes, inspect your environment to determine which steps can be skipped:

## Check if the gws CLI is installed
which gws && gws --version

## Verify if OAuth client credentials exist
ls ~/.config/gws/client_secret.json

## Check current authentication status
gws auth status

If the authentication status shows "status": "success" and the required scopes are present, you can skip directly to skill installation.

2. Install the Google Workspace

CLI

If gws is not installed, run the following:

npm install -g @googleworkspace/cli
gws --version

This installs the CLI globally and ensures it is available in your shell.

3. Set Up GCP Project and OAuth

Credentials

You need to create OAuth 2.0 credentials in the Google Cloud Console:

• Go to Google Cloud Console.
• Create a new project (name it descriptively, e.g., Workspace Automation).
• Enable the APIs you plan to use (e.g., Gmail, Drive, Calendar).
• Navigate to APIs & Services > Credentials.
• Click Create Credentials > OAuth client ID.
• Choose Desktop app as the application type.
• Download the client_secret.json file and place it at ~/.config/gws/client_secret.json.

4. Authenticate the

CLI

Initiate the OAuth flow to authenticate your CLI:

gws auth login --client-secrets ~/.config/gws/client_secret.json

Follow the browser prompts to grant access to your Google account.

5. Confirm

Authentication

Verify the authentication status:

gws auth status

A successful status should display the authenticated user and granted scopes.

6. Install Agent Skills for Claude

Code

To enable extended capabilities, install the suite of Claude Code agent skills:

gws skills install --all

This step unlocks advanced automation for Gmail, Drive, Calendar, Sheets, Docs, Chat, and more.

Key Features

• End-to-End Setup Automation: Covers everything from CLI installation to full OAuth authentication.
• Intelligent Workflow Skipping: Detects completed steps and avoids redundant actions.
• Bulk Skill Installation: Seamlessly adds 90+ Claude Code agent skills, broadening automation capabilities.
• Compatibility Checks: Ensures environment prerequisites are met before proceeding.
• Troubleshooting Guidance: Offers targeted advice for common errors, especially around OAuth and API access.

Best Practices

• Use a Dedicated GCP Project: Keep your automation environment isolated from other projects for better manageability and security.
• Store Credentials Securely: Protect client_secret.json and any generated tokens using file system permissions.
• Regularly Update the CLI: Keep @googleworkspace/cli up to date to benefit from the latest features and security patches.
• Limit API Scopes: Grant only the minimum required API scopes during OAuth setup for improved security.
• Document Setup Steps: Maintain a setup log or documentation for team onboarding and future troubleshooting.

Important Notes

• Claude Code Only: Gws Setup is designed specifically for Claude Code environments and is not intended for generic application automation.
• Google API Quotas: Be mindful of API usage limits and quotas, especially when enabling bulk automation.
• Manual Steps Required: While Gws Setup automates much of the process, certain steps—such as cloud project and credential creation—require manual intervention due to Google Cloud Console UI limitations.
• Credential Security: Never share your OAuth client secrets or tokens. Rotate credentials if you suspect compromise.
• Skill Updates: As Google Workspace and Claude Code evolve, periodically revisit skill installations to ensure compatibility and access to new features.

By following the Gws Setup workflow, developers and administrators can quickly configure a robust foundation for advanced Google Workspace automation using Claude Code, reducing setup friction and unlocking powerful integration scenarios.