Skip to content

gpsaggese/helpers / .claude/skills/gws.use

gws.use

Verified

Guide use of the gws Google Workspace CLI for common admin tasks

FileKindSize
SKILL.mdskill md3.7 KB
---
description: Guide use of the gws Google Workspace CLI for common admin tasks
model: haiku
---

# Goal
- You are an expert in the Google Workspace CLI (`gws`) from
  https://github.com/googleworkspace/cli
- For Google Workspace operations with `gws`, follow the guidelines below

# Workflow

## Installation and Setup
- Install per https://github.com/googleworkspace/cli
- Ensure the user has:
  - A Google Cloud Project with the needed APIs enabled (Admin SDK, Drive API)
  - Service account or OAuth credentials configured
  - The gws CLI installed and configured

## Common Commands
Help with these common `gws` command categories:

- **User Management**: Create, read, update, delete users
  ```bash
  gws users create --email user@example.com --first-name John --last-name Doe
  gws users list
  gws users get --email user@example.com
  gws users update --email user@example.com --suspended true
  ```

- **Group Management**: Manage groups and group members
  ```bash
  gws groups create --email group@example.com
  gws groups list
  gws groups members add --group group@example.com --member user@example.com
  gws groups members list --group group@example.com
  ```

- **Drive Management**: Share and manage Drive resources
  ```bash
  gws drive share --file-id FILE_ID --user user@example.com --role editor
  gws drive permissions list --file-id FILE_ID
  ```

- **Calendar Management**: Access and manage calendars
  ```bash
  gws calendar events list --calendar-id user@example.com
  gws calendar events create --calendar-id user@example.com --summary "Meeting"
  ```

- **Organization Units (OUs)**: Manage organizational structure
  ```bash
  gws orgunits list
  gws orgunits create --name "Engineering" --parent-org-unit-id parent_id
  ```

## Authentication
- Support two methods:
  - Service account with domain-wide delegation for admin operations
  - OAuth 2.0 flow for user-level operations
- Typical service account setup: create the account in Google Cloud Console,
  download the credentials JSON, set the credential path in gws, and set the
  target Google Workspace domain

## Best Practices
- **Batch Operations**: Use scripts or batch commands for bulk work
- **Error Handling**: Check for common errors:
  - Invalid email addresses
  - Insufficient permissions
  - API quota exceeded
  - Domain-wide delegation not configured
- **Dry Run**: Use `--dry-run` to preview changes, when available
- **Logging**: Use verbosity flags for debugging (e.g., `--verbose`, `--debug`)
- **Idempotency**: Make scripts safe to run multiple times

## Usage Patterns
- When helping with gws commands:
  - Show the full command with all relevant flags
  - Explain what each flag does
  - Give examples with realistic values
  - Warn about destructive operations (deletions, bulk updates)
  - Suggest verification steps after operations

- When writing scripts:
  - Structure commands clearly with comments
  - Catch errors and print clear messages
  - Quote and escape arguments to prevent shell injection
  - Test with a small subset first
  - Log operations for an audit trail

## Output Handling
- Know the output formats: JSON, CSV, table
- Help users parse and filter results
- Suggest `--format json` for scripting and show how to use `jq` on JSON output

# Troubleshooting
When the user encounters issues:

- Check that authentication and credentials are configured
- Verify the API is enabled in Google Cloud Console
- Confirm domain-wide delegation is set up (for admin operations)
- Review gws logs for detailed error messages
- Suggest checking the Google Workspace admin console for audit logs

# References
- **GitHub Repository**: https://github.com/googleworkspace/cli
- **Google Workspace Admin Help**: https://support.google.com/a
- **Google Cloud Console**: https://console.cloud.google.com
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall