google-workspace-cli

Q: How do I install google-workspace-cli?

Run npx skills add https://github.com/alirezarezvani/claude-skills --skill google-workspace-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/google-workspace-cli/ (personal) or .claude/skills/google-workspace-cli/ (project).

by alirezarezvaniProductivity & Automation

Google Workspace administration via the gws CLI (github.com/googleworkspace/cli). Install, authenticate, and automate Gmail, Drive, Sheets, Calendar, Docs, Chat, and Tasks. Run security audits and use local recipe templates and persona bundles. Use for Google Workspace admin, gws CLI setup, Gmail automation, Drive management, or Calendar scheduling.

Installs: 638
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/alirezarezvani/claude-skills --skill google-workspace-cli

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads google-workspace-cli automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Google Workspace CLI

Expert guidance and automation for Google Workspace administration using the open-source gws CLI (github.com/googleworkspace/cli, Apache-2.0). The CLI builds its command surface dynamically from Google's Discovery Service, so it covers every supported Workspace API plus +-prefixed helper commands. This skill adds local Python tools (doctor, auth guide, recipe catalog, security audit, output analyzer).

Verify before scripting: gws generates commands at runtime from Google's API discovery documents, and the CLI is pre-v1.0. Always confirm a command's exact surface with gws --help, gws <service> --help, or gws schema <service>.<resource>.<method> before putting it in automation. Commands in this skill marked (verify) are illustrative of the gws <service> <resource> <method> pattern and must be checked against your installed version.

Quick Start

Check Installation

# Verify gws is installed and authenticated
python3 scripts/gws_doctor.py

Send an Email

gws gmail +send --to "team@company.com" \
  --subject "Weekly Update" --body "Here's this week's summary..."

List Drive Files

gws drive files list --params '{"pageSize": 20}' | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table

Installation

npm (recommended; requires Node.js 18+)

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

Homebrew (macOS/Linux)

brew install googleworkspace-cli

Cargo (from source)

cargo install --git https://github.com/googleworkspace/cli --locked
gws --version

Pre-built Binaries

Download from github.com/googleworkspace/cli/releases for macOS, Linux, or Windows. Nix users: nix run github:googleworkspace/cli.

Verify Installation

python3 scripts/gws_doctor.py
# Checks: PATH, version, auth status, service connectivity

Authentication

OAuth Setup (Interactive)

# Step 1: Create Google Cloud project and OAuth credentials
python3 scripts/auth_setup_guide.py --guide oauth

# Step 2: Run interactive auth setup (uses gcloud if available)
gws auth setup

# Step 3: Log in, requesting only the scopes you need
gws auth login -s drive,gmail,sheets

Headless/CI

# Generate setup instructions
python3 scripts/auth_setup_guide.py --guide service-account

# Export credentials from an interactive machine, then point the CLI at them
gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

Environment Variables

# Generate .env template
python3 scripts/auth_setup_guide.py --generate-env

Variable	Purpose
`GOOGLE_WORKSPACE_CLI_CLIENT_ID`	OAuth client ID
`GOOGLE_WORKSPACE_CLI_CLIENT_SECRET`	OAuth client secret
`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`	Path to exported credentials JSON
`GOOGLE_WORKSPACE_CLI_TOKEN`	Pre-obtained OAuth token
`GOOGLE_WORKSPACE_CLI_CONFIG_DIR`	Override default config location
`GOOGLE_WORKSPACE_CLI_LOG`	Enable debug logging

Validate Authentication

python3 scripts/auth_setup_guide.py --validate --json
# Tests each service endpoint

Workflow 1: Gmail Automation

Goal: Automate email operations — send, search, label, and filter management.

Send, Reply, Forward (helper commands)

# Send a new email
gws gmail +send --to "client@example.com" \
  --subject "Proposal" --body "Please find attached..."

# Reply to a message (auto-threading); check exact flags with: gws gmail +reply --help
gws gmail +reply ...

# Forward a message; check exact flags with: gws gmail +forward --help
gws gmail +forward ...

# Unread inbox summary
gws gmail +triage

Search and Inspect (discovery commands)

Discovery commands follow gws <service> <resource> <method> and take request parameters as JSON via --params (query/path params) and --json (request body). Inspect any method's exact schema first:

# What does messages.list accept? (verify)
gws schema gmail.users.messages.list

# Search emails (verify against the schema above)
gws gmail users messages list --params '{"userId": "me", "q": "from:client@example.com after:2025/01/01"}' \
  | python3 scripts/output_analyzer.py --count

# List labels (verify)
gws gmail users labels list --params '{"userId": "me"}'

Bulk Operations

Use --dry-run first, and --page-all to paginate (one JSON line per page):

# Preview, then archive read emails older than 30 days (verify method schema first)
gws gmail users messages list --params '{"userId": "me", "q": "is:read older_than:30d"}' --page-all \
  | python3 scripts/output_analyzer.py --select "id" --format json
# Then feed ids to gmail users messages modify (see: gws schema gmail.users.messages.modify)

Workflow 2: Drive & Sheets

Goal: Manage files, create spreadsheets, configure sharing, and export data.

File Operations

# List files
gws drive files list --params '{"pageSize": 50}' \
  | python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table

# Upload a file (helper)
gws drive +upload ./report.pdf --name "Q1 Report"

# Create a Google Sheet
gws sheets spreadsheets create --json '{"properties": {"title": "Budget 2026"}}'

# Download/export — inspect the method first (verify)
gws schema drive.files.export

Sharing (verify schemas first)

# Inspect the permissions API surface
gws schema drive.permissions.create

# Share with user (verify against schema)
gws drive permissions create --params '{"fileId": "<FILE_ID>"}' \
  --json '{"type": "user", "role": "writer", "emailAddress": "colleague@company.com"}'

# List who has access (verify)
gws drive permissions list --params '{"fileId": "<FILE_ID>"}'

Sheets Data

# Read values (helper); check exact flags with: gws sheets +read --help
gws sheets +read ...

# Append a row (helper); check exact flags with: gws sheets +append --help
gws sheets +append ...

# Or use discovery methods (verify):
gws schema sheets.spreadsheets.values.update
gws sheets spreadsheets values get --params '{"spreadsheetId": "<SHEET_ID>", "range": "Sheet1!A1:D10"}'

Workflow 3: Calendar & Meetings

Goal: Schedule events, find available times, and generate standup reports.

Event Management

# Create an event (helper); check exact flags with: gws calendar +insert --help
gws calendar +insert ...

# Upcoming events (helper, timezone-aware)
gws calendar +agenda

# Or via discovery (verify):
gws schema calendar.events.insert
gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}'

Find Available Time

# Free/busy via the Calendar API (verify schema first)
gws schema calendar.freebusy.query
gws calendar freebusy query --json '{"timeMin": "...", "timeMax": "...", "items": [{"id": "alice@co.com"}]}'

Standup Report (workflow helpers)

# Today's meetings + tasks
gws workflow +standup-report \
  | python3 scripts/output_analyzer.py --format table

# Next meeting prep; check exact flags with: gws workflow +meeting-prep --help
gws workflow +meeting-prep

Workflow 4: Security Audit

Goal: Audit Google Workspace security configuration and generate remediation commands.

Run Full Audit

# Full audit across all services
python3 scripts/workspace_audit.py --json

# Audit specific services
python3 scripts/workspace_audit.py --services gmail,drive,calendar

# Demo mode (no gws required)
python3 scripts/workspace_audit.py --demo

Audit Checks

Area	Check	Risk
Drive	External sharing enabled	Data exfiltration
Gmail	Auto-forwarding rules	Data exfiltration
Gmail	DMARC/SPF/DKIM records	Email spoofing
Calendar	Default sharing visibility	Information leak
OAuth	Third-party app grants	Unauthorized access
Admin	Super admin count	Privilege escalation
Admin	2-Step verification enforcement	Account takeover

Review and Remediate

# Review findings
python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py \
  --filter "status=FAIL" --select "area,check,remediation"

# Execute remediation (example: check current Drive settings first; verify)
gws drive about get --params '{"fields": "*"}'
# Follow remediation commands from audit output (verify each against gws --help)

Python Tools

Script	Purpose	Usage
`gws_doctor.py`	Pre-flight diagnostics	`python3 scripts/gws_doctor.py [--json] [--services gmail,drive]`
`auth_setup_guide.py`	Guided auth setup	`python3 scripts/auth_setup_guide.py --guide oauth`
`gws_recipe_runner.py`	Recipe catalog & runner	`python3 scripts/gws_recipe_runner.py --list [--persona pm]`
`workspace_audit.py`	Security/config audit	`python3 scripts/workspace_audit.py [--json] [--demo]`
`output_analyzer.py`	JSON/NDJSON analysis	`gws ... --json \| python3 scripts/output_analyzer.py --count`

All scripts are stdlib-only, support --json output, and include demo mode with embedded sample data.

Best Practices

Security

Use OAuth with minimal scopes — request only what each workflow needs
Store tokens in the system keyring, never in plain text files
Rotate service account keys every 90 days
Audit third-party OAuth app grants quarterly
Use --dry-run before bulk destructive operations

Automation

All gws output is structured JSON — pipe it through output_analyzer.py for filtering and aggregation
Use gws workflow +* helpers for multi-step operations instead of chaining raw commands
Use the local recipe catalog (gws_recipe_runner.py) as command templates, then verify each against gws --help
--page-all emits one JSON line per page (NDJSON) for streaming large result sets
Use --dry-run to preview any request before executing it

Performance

Request only needed fields via the API's fields parameter in --params (reduces payload size)
Use pageSize in --params to cap results when browsing
Use --page-all only when you need complete datasets; tune with --page-limit / --page-delay
Prefer + helpers (single optimized calls) over hand-chained API calls
Cache frequently accessed data (e.g., label IDs, folder IDs) in variables

Limitations

Constraint	Impact
OAuth tokens expire after 1 hour	Re-auth needed for long-running scripts
API rate limits (per-user, per-service)	Bulk operations may hit 429 errors
Scope requirements vary by service	Must request correct scopes during auth
Pre-v1.0 CLI status	Breaking changes possible between releases
Google Cloud project required	Free, but requires setup in Cloud Console
Admin API needs admin privileges	Some audit checks require Workspace Admin role

Required Scopes by Service

# List scopes for specific services
python3 scripts/auth_setup_guide.py --scopes gmail,drive,calendar,sheets

Service	Key Scopes
Gmail	`gmail.modify`, `gmail.send`, `gmail.labels`
Drive	`drive.file`, `drive.metadata.readonly`
Sheets	`spreadsheets`
Calendar	`calendar`, `calendar.events`
Admin	`admin.directory.user.readonly`, `admin.directory.group`
Tasks	`tasks`

FAQ

What does the google-workspace-cli skill do?

How do I install google-workspace-cli?

Run npx skills add https://github.com/alirezarezvani/claude-skills --skill google-workspace-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/google-workspace-cli/ (personal) or .claude/skills/google-workspace-cli/ (project).

Which AI agents can use google-workspace-cli?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is google-workspace-cli safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains google-workspace-cli?

It is published by alirezarezvani in alirezarezvani/claude-skills. It has 638 recorded installs.

More from alirezarezvani/claude-skills

View all →

engineering-skills

alirezarezvani/claude-skills

Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365 (stdlib-only Python tools). Use when browsing or choosing among engineering-team role skills — load only the one specialist SKILL.md you need, never bulk-load the bundle.

Backend & APIs2.4K installs

finance-skills

alirezarezvani/claude-skills

Router/index for the finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts), saas-metrics-coach (ARR/MRR, churn, CAC/LTV, NRR, quick ratio) and month-end-close (close calendar, reconciliations, flux review). Use when a finance request doesn't obviously match one skill and you need to pick the right one (e.g., 'analyze these financials', 'how healthy are my SaaS metrics').

Business & Finance2.3K installs

marketing-skills

alirezarezvani/claude-skills

Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing capabilities exist, or get oriented in this plugin. 44 specialist skills across 8 pods (content, SEO + AEO, CRO, channels, growth, intelligence, sales enablement, ops), 59 stdlib Python tools. Routes to one skill — it does not execute marketing work itself.

Marketing & SEO2.3K installs

business-growth-skills

alirezarezvani/claude-skills

Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion), sales-engineer (RFP analysis, competitive matrices, PoC planning), revenue-operations (pipeline, forecast accuracy, GTM efficiency), and contract-and-proposal-writer. Use when a growth/revenue request doesn't obviously match one skill and you need to pick the right one (e.g., 'which accounts are at risk', 'should we bid on this RFP').

Business & Finance2.2K installs

engineering-advanced-skills

alirezarezvani/claude-skills

Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the POWERFUL-tier engineering skills: agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, changelog/release automation, reliability (SLO/chaos/flags/operators), platform ops.

AI & Agents2K installs

product-skills

alirezarezvani/claude-skills

Use when coordinating product work across the 12 bundled product sub-skills (RICE, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding) or the 4 standalone product-team plugins (user stories, Apple HIG, code-to-PRD, research summarizer). Triggers on 'help me prioritize', 'plan a product experiment', 'we ship features nobody uses', 'run the discovery loop', 'is our OST sound'. Forks context to route to one sub-skill via a deterministic signal router and returns a digest; can also drive a continuous-discovery loop (Torres cadence tracker + OST linter as machine gates) or a full goal→plan→execute→verify→close run through the repo-wide agent-harness. Distinct from project-management (how to deliver vs what to build), marketing/landing (from-scratch pages), and engineering/agent-harness (the generic loop engine this orchestrator plugs into).

Code Quality & Workflow2K installs

Popular productivity & automation skills

View category →

agent-browser

vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.

OfficialProductivity & Automation1.3M installs

lark-doc

open.feishu.cn

飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由；/page/ 是妙搭应用，非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。

Productivity & Automation815.7K installs

lark-base

open.feishu.cn

飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。

Productivity & Automation815K installs

lark-drive

open.feishu.cn

飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签（secure labels）和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。

Productivity & Automation815K installs

lark-shared

open.feishu.cn

Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling notice JSON.

Productivity & Automation814.8K installs

lark-im

open.feishu.cn

飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。

Productivity & Automation814.1K installs

google-workspace-cli

Install

Install

Describe the task

Review the result

SKILL.md

Google Workspace CLI

Quick Start

Check Installation

Send an Email

List Drive Files

Installation

npm (recommended; requires Node.js 18+)

Homebrew (macOS/Linux)

Cargo (from source)

Pre-built Binaries

Verify Installation

Authentication

OAuth Setup (Interactive)

Headless/CI

Environment Variables

Validate Authentication

Workflow 1: Gmail Automation

Send, Reply, Forward (helper commands)

Search and Inspect (discovery commands)

Bulk Operations

Workflow 2: Drive & Sheets

File Operations

Sharing (verify schemas first)

Sheets Data

Workflow 3: Calendar & Meetings

Event Management

Find Available Time

Standup Report (workflow helpers)

Workflow 4: Security Audit

Run Full Audit

Audit Checks

Review and Remediate

Python Tools

Best Practices

Security

Automation

Performance

Limitations

Required Scopes by Service

FAQ

More from alirezarezvani/claude-skills

Popular productivity & automation skills