gworkspace-cli
Google Workspace via the gws CLI (Drive/Sheets/Docs/Gmail/Calendar/Chat/Admin). Use when the agent needs to read or write any Workspace data such as Drive files, Sheets values, Docs content, Gmail messages, Calendar events, Chat messages, or Admin SDK objects.
- License 许可
- MIT
- 所属仓库
- muratovv/ai-hats
- 最近更新
- 2026-11-05
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- gworkspace-cli
- license
- MIT
- description
- Google Workspace via the gws CLI (Drive/Sheets/Docs/Gmail/Calendar/Chat/Admin). Use when the agent needs to read or write any Workspace data such as Drive files, Sheets values, Docs content, Gmail messages, Calendar events, Chat messages, or Admin SDK objects.
03 SKILL.md 正文
Google Workspace CLI (gws)
Single-command access to Google Workspace APIs through one gws binary on $PATH. Use when the agent needs to read or write any Workspace data: Drive files, Sheets values, Docs content, Gmail messages, Calendar events, Chat messages, or Admin SDK objects.
When to Use
This skill covers using gws to read/write Workspace data once it is
installed and authenticated. The boundary cases worth flagging:
- Install / auth not done (
gwsmissing, orgws auth statusreports no creds) → don't improvise the setup; surfacedocs/integrations/gworkspace-cli-setup.mdand walk the user through it. - The
admingroup (users, groups, org units) needs Workspace-admin credentials — out of reach for an ordinary delegated account; don't reach for it on a normal user's behalf.
Setup
If gws is not installed, or gws auth status reports no active credentials — open docs/integrations/gworkspace-cli-setup.md and walk the user through install, auth, and permission-allowlist steps. Do not try to install or authenticate without surfacing the guide.
Top-level command groups
| Group | Purpose |
|---|---|
drive |
Files, folders, sharing, copy/move/trash |
sheets |
Spreadsheets, values, batch updates |
docs |
Documents, structured content edits |
gmail |
Threads, messages, labels, send |
calendar |
Calendars, events, agenda |
chat |
Spaces, messages |
admin |
Users, groups, org units (Workspace admin only) |
Discovery
Commands are generated dynamically from Google's Discovery Service plus hand-crafted helpers (prefixed +):
gws --help # all groups
gws <group> --help # methods in a group
gws <group> <method> --help # params for a single method
When unsure which method fits — start from gws <group> --help, then narrow.
Common patterns
Read a range:
gws sheets spreadsheets values get \
--params '{"spreadsheetId":"<id>","range":"Sheet1!A:Z"}' \
--format csv
Append a row (dates and formulas parsed):
gws sheets spreadsheets values append \
--params '{"spreadsheetId":"<id>","range":"Sheet1!A1","valueInputOption":"USER_ENTERED"}' \
--json '{"values":[["2026-05-18","value"]]}'
Find a file by name:
gws drive files list \
--params '{"q":"name = '\''Report'\'' and trashed = false","fields":"files(id,name)"}'
Safety & conventions
- No secrets in code or examples. Auth state lives in
~/.config/gws/(AES-256-GCM at rest); never embed tokens, client secrets, or service-account keys. - Identifiers via env, not hardcode. Spreadsheet IDs, folder IDs, etc. — read from environment or config files, not literal strings.
USER_ENTEREDfor values that contain dates, numbers, or formulas;RAWonly for verbatim strings.- Append-only for journals. Use
values append(notupdate) for transaction logs; never overwrite history. - Snapshot before destructive writes.
gws drive files copythe spreadsheet/doc before bulk writes to critical sheets. - CLI resolves via
$PATH. No hardcoded install paths; ifgwsis missing, surface the setup guide.
Anti-patterns
- Hardcoding spreadsheet/folder IDs in scripts or skill content.
- Writing tokens or OAuth secrets into the repo or skill files.
- Using
RAWwhen the values include dates or formulas — they end up as plain strings. - Overwriting an append-only journal sheet with
values update. - Calling
gwsfrom a fully qualified path (/usr/local/bin/gws) — break portability. - Bulk writes without a prior
gws drive files copysnapshot.
04 同仓库更多 Skills
tool-evaluation-protocol
Time-bounded protocol for evaluating new tools, libraries, or methodologies before adoption. Use when evaluating a candidate dependency for the project, researching a methodology (e.g. ML/LLM frameworks, testing approaches), or following up on a hype-driven recommendation.
systematic-debugging
4-phase bug-fix protocol (evidence, pattern, hypothesis, verify). Use when investigating any error, failure, or unexpected behavior, handling bug reports from users or monitoring, or diagnosing test failures with non-obvious causes.
skill-template
Canonical template and validation guide for ai-hats skills. Use when creating a new skill, reviewing an existing one for structural compliance, or deciding which pattern fits a new behavior.
skill-optimization
Audit and refactor library components to eliminate redundancy and staleness. Use during periodic library maintenance, after adding multiple new skills or rules, when a role's token budget is too high, or after retrospectives identify component issues.
silent-fallback-gate
PreToolUse hook — refuses an Edit or Write that adds an inert broad except. Use when a Python edit was blocked for a silent fallback.
retro-to-framework
Convert an observation about agent behavior — from a retrospective or from a single incident — into a framework-level change (hook, rule, skill, skill update). Use after a retrospective identifies problems that are not project-specific, after an incident where an agent misapplied a component it had read, when CLAUDE.md band-aids accumulate (more than 3 per-project rules that could be generic), or when the same problem recurs across multiple projects.