gws-install

SKILL.md

Google Workspace CLI — Quick Install

Install gws on an additional machine using OAuth credentials from a previous setup. Produces an authenticated CLI with all agent skills ready to use.

Prerequisite: The user must have client_secret.json from a previous gws-setup (or from Google Cloud Console). If they don't have it, use the gws-setup skill instead.

Workflow

Step 1: Pre-flight Checks

which gws && gws --version
ls ~/.config/gws/client_secret.json
gws auth status

If already authenticated with the right scopes, skip to Step 4.

Step 2: Install the CLI
npm install -g @googleworkspace/cli
gws --version

Step 3: Set Up Credentials

Ask the user to provide their client_secret.json. Three options:

Option A — Paste the JSON content:

Ask the user to paste the JSON. Write it to ~/.config/gws/client_secret.json:

mkdir -p ~/.config/gws

Expected format:

{
  "installed": {
    "client_id": "...",
    "project_id": "...",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "client_secret": "...",
    "redirect_uris": ["http://localhost"]
  }
}

Option B — File path:

If the user has the file locally (e.g. in Downloads):

mkdir -p ~/.config/gws
cp /path/to/client_secret.json ~/.config/gws/client_secret.json

Option C — Environment variables:

export GOOGLE_WORKSPACE_CLI_CLIENT_ID="your-client-id"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="your-client-secret"

Step 4: Authenticate

IMPORTANT: This step prints a very long OAuth URL (30+ scopes) that the user must open in their browser. The URL is too long to copy from terminal output — it wraps across lines and breaks. Always extract it to a file and open it programmatically.

Ask which Google account to use, then:

Run auth in the background and capture output:

gws auth login -s gmail,drive,calendar,sheets,docs,chat,tasks 2>&1 | tee /tmp/gws-auth-output.txt

Running as a background task is fine — it will complete once the user approves in browser.

Extract and open the URL (run separately after output appears):

grep -o 'https://accounts.google.com[^ ]*' /tmp/gws-auth-output.txt > /tmp/gws-auth-url.txt
cat /tmp/gws-auth-url.txt | xargs open

If open doesn't work, tell the user: "The auth URL is saved at /tmp/gws-auth-url.txt — open that file and copy the URL from there."

Wait for the user to approve in their browser, then verify:

gws auth status

Alternative — --full for all scopes:

gws auth login --full

The user can check their original machine's scopes with gws auth status to see what was granted.

Step 5: Install Agent Skills

npx skills add googleworkspace/cli -g --agent claude-code --all

This installs 90+ skills into ~/.claude/skills/. Safe to re-run if skills are already installed.

Step 6: Verify

gws auth status
gws calendar +agenda --today
gws gmail +triage

Troubleshooting

"Auth error — credentials missing or invalid" (exit code 2)

Check ~/.config/gws/client_secret.json exists and has valid JSON

Re-run gws auth login

Token expired

If the GCP app is in "Testing" status, tokens expire after 7 days

Re-run gws auth login to refresh

For permanent tokens, push the app to Production in GCP Console OAuth consent screen

Skills not appearing in Claude Code

Skills load at session start — restart Claude Code after installing

Verify: ls ~/.claude/skills/gws-* | wc -l should show 30+ directories

See Also

gws-setup — First-time setup including GCP project creation

gws-shared — Auth patterns and global flags