From 3ed52354a08a5953fa36817565fdbe2ca51e65c3 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 5 May 2026 02:47:31 +0100 Subject: [PATCH] docs(skill): improve gog agent guidance (#552) Co-authored-by: Tim Pietrusky --- .agents/skills/gog/SKILL.md | 161 +++++++++++++++++++++++++----------- CHANGELOG.md | 1 + README.md | 25 ++++-- docs/README.md | 3 + 4 files changed, 135 insertions(+), 55 deletions(-) diff --git a/.agents/skills/gog/SKILL.md b/.agents/skills/gog/SKILL.md index 19bd1ea..86b00c8 100644 --- a/.agents/skills/gog/SKILL.md +++ b/.agents/skills/gog/SKILL.md @@ -1,58 +1,125 @@ --- name: gog -description: Use when gog should fill Google connector gaps for Gmail, Calendar, Drive, Docs, Sheets, Chat, or Contacts. +description: Use when working with the gog CLI for Google Workspace automation, especially when an agent needs JSON output, auth preflight, command guards, scoped accounts, or safe Google API reads/writes across Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Contacts, Tasks, People, Groups, Keep, or Admin. --- # gog -Use `gog` as a local Google services CLI when built-in connectors are missing a feature, need shell-friendly JSON, or need account/auth inspection. +Use `gog` when built-in Google connectors are missing a feature, when shell +automation needs stable JSON, or when you need to inspect local Google auth +state before acting. -## Sources - -- Repo: `~/Projects/gogcli` -- CLI: `gog` -- Config: `~/Library/Application Support/gogcli/config.json` -- OAuth/keyring: `~/Library/Application Support/gogcli` - -## Auth - -Inspect accounts before assuming auth is blocked: - -```bash -gog auth list -gog auth status -``` - -Use `--json` for scriptable output and `--dry-run` for write planning where supported. - -## Common Surfaces - -```bash -gog gmail search "from:example@example.com" -gog calendar events list --json -gog drive search "name contains 'deck'" --json -gog contacts search "Name" --json -gog sheets --help -``` - -Prefer native Gmail/Calendar/Drive/Slack connectors first when they cover the task. Use `gog` for gaps, local automation, or auth/debug state. - -## Safety - -Do not send email, create/update/delete files, change calendar events, or alter contacts unless the user explicitly asks. For writes, summarize the target account and intended mutation first unless the user already gave a concrete command. - -## Verification - -For repo edits: - -```bash -make test -make -``` - -Smoke: +## Fast Path ```bash gog --version -gog auth status --json +gog auth list --check --json --no-input +gog auth doctor --check --json --no-input +gog schema --json ``` + +Pick the account explicitly for API work: + +```bash +gog --account user@example.com gmail search 'newer_than:7d' --json +``` + +Prefer `--json` or `--plain` for agent parsing. Human hints and progress should +stay on stderr; stdout is for data. + +## Safety Rules + +- Do not print access tokens, refresh tokens, OAuth client secrets, or keyring + passwords. +- Do not store `GOG_KEYRING_PASSWORD` in a shell profile or plaintext project + file. If the file keyring cannot unlock non-interactively, stop and ask for a + safer setup. +- Use `--no-input` in automation so auth/keyring prompts fail clearly. +- Use `--dry-run` first where commands support it. +- Destructive commands require `--force`; do not add it unless the user asked + for that exact mutation. +- Use `--gmail-no-send` or `GOG_GMAIL_NO_SEND=1` unless sending mail is the + requested task. +- For shared agent environments, prefer a baked readonly or agent-safe binary + from `docs/safety-profiles.md`. + +Runtime command guards: + +```bash +gog --enable-commands gmail.search,gmail.get --gmail-no-send \ + --account user@example.com gmail search 'from:example@example.com' --json + +gog --enable-commands drive.ls,docs.cat --disable-commands drive.delete \ + --account user@example.com drive ls --max 10 --json +``` + +## Auth + +OAuth setup is partly interactive. An agent can inspect and diagnose it, but a +human normally completes browser consent: + +```bash +gog auth credentials list +gog auth add user@example.com --services gmail,calendar,drive --readonly +gog auth add user@example.com --services docs,sheets,slides +gog auth remove user@example.com +``` + +Use narrow services and `--readonly` when the task only reads. Service accounts +are Workspace-only and mainly fit Admin, Groups, Keep, and domain-wide +delegation flows; they do not solve consumer `@gmail.com` OAuth. + +## Common Reads + +```bash +gog --account user@example.com gmail search 'newer_than:3d' --max 10 --json +gog --account user@example.com gmail get --sanitize-content --json +gog --account user@example.com gmail thread get --sanitize-content --json + +gog --account user@example.com calendar events --today --json +gog --account user@example.com drive ls --max 20 --json +gog --account user@example.com docs cat --json +gog --account user@example.com sheets get Sheet1!A1:D20 --json +gog --account user@example.com contacts list --max 20 --json +``` + +For Gmail body inspection, prefer `--sanitize-content` unless the user +explicitly needs raw payloads. + +## Writes + +Before writes, identify the account, object id, and exact mutation. Prefer +commands that support `--dry-run`, and clean up disposable live-test objects. + +```bash +gog --account user@example.com docs write --append --text '...' +gog --account user@example.com sheets update Sheet1!A1 --values-json '[["hello"]]' +gog --account user@example.com drive upload ./file.txt --parent --json +``` + +When testing creation commands, name artifacts with a clear temporary prefix and +delete or trash them after verification. + +## Discovery + +Use generated command docs and schema instead of guessing flags: + +```bash +gog --help +gog --help +gog schema --json +``` + +Docs: + +- `docs/README.md` +- `docs/commands/README.md` +- `docs/safety-profiles.md` +- `README.md#security` + +Repo paths: + +- CLI entrypoint: `cmd/gog/` +- Command implementations: `internal/cmd/` +- OAuth/keyring: `internal/auth/`, `internal/secrets/` +- Generated command docs: `docs/commands/` diff --git a/CHANGELOG.md b/CHANGELOG.md index af07893..4a030ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ - Sheets: add `sheets table append` for appending rows to structured Sheets tables without targeting headers directly. - Sheets: add header-safe `sheets table clear` for clearing table data rows without touching headers or footers. - Sheets: add `sheets conditional-format` and `sheets banding` commands for rule-based formatting and alternating color banded ranges. (#378) — thanks @codBang. +- Agent docs: add a bundled `gog` skill for safe JSON-first Google Workspace automation from coding agents. (#353, #451) — thanks @TimPietrusky and @sluramod. ### Fixed - Agent safety: compile baked safety profile policies into generated hash switches so raw allow/deny rule strings are not embedded as patchable YAML. (#540) — thanks @drewburchfield. diff --git a/README.md b/README.md index 3f61d34..5c441a5 100644 --- a/README.md +++ b/README.md @@ -79,17 +79,19 @@ For authenticated automation in a container, mount a persistent config directory docker volume create gogcli-config docker run --rm -it \ -e GOG_KEYRING_BACKEND=file \ - -e GOG_KEYRING_PASSWORD='change-me' \ + -e GOG_KEYRING_PASSWORD \ -v gogcli-config:/home/gog/.config/gogcli \ ghcr.io/steipete/gogcli:latest auth add you@gmail.com --services gmail,calendar,drive ``` -Subsequent runs can reuse the same volume and password: +Subsequent runs can reuse the same volume and password. Set +`GOG_KEYRING_PASSWORD` in the shell session or CI secret store before running +the container; do not bake it into scripts or profiles. ```bash docker run --rm \ -e GOG_KEYRING_BACKEND=file \ - -e GOG_KEYRING_PASSWORD='change-me' \ + -e GOG_KEYRING_PASSWORD \ -v gogcli-config:/home/gog/.config/gogcli \ ghcr.io/steipete/gogcli:latest gmail labels list --account you@gmail.com ``` @@ -361,10 +363,8 @@ Non-interactive runs (CI/ssh): file backend requires `GOG_KEYRING_PASSWORD`. The file backend uses portable encoded filenames for stored keys, so account tokens work on Windows even when key names contain colons. If you see `aes.KeyUnwrap(): integrity check failed`, first run `gog auth doctor`; the usual cause is that different shells/services/agents are using different `GOG_KEYRING_PASSWORD` values for the same encrypted token files. -```bash -export GOG_KEYRING_PASSWORD='...' -gog --no-input auth status -``` +Inject the password from a secret manager or the current shell session only; do +not save it in shell profiles, docs, or project files. Force backend via env (overrides config): @@ -644,6 +644,10 @@ For stronger isolation, build a dedicated binary with an embedded safety profile Baked profiles are checked after CLI parsing and before any command runs. They are fail-closed and cannot be changed by config, environment variables, or runtime allowlist flags. See `docs/safety-profiles.md`. + +Agents can also use the bundled `gog` skill at `.agents/skills/gog/SKILL.md` +for auth preflight, JSON-first command patterns, and safe Google Workspace +automation defaults. ## Security @@ -657,6 +661,9 @@ OAuth credentials are stored securely in your system's keychain: The CLI uses [github.com/99designs/keyring](https://github.com/99designs/keyring) for secure storage. If no OS keychain backend is available (e.g., Linux/WSL/container), keyring can fall back to an encrypted on-disk store and may prompt for a password; for non-interactive runs set `GOG_KEYRING_PASSWORD`. +Treat `GOG_KEYRING_PASSWORD` as a secret: inject it from your CI secret store or +session environment, and do not put it in `.zshrc`, shell profiles, docs, or +project files. ### Keychain Prompts (macOS) @@ -2050,7 +2057,9 @@ export GOG_CLIENT=work go test -tags=integration ./... ``` -Tip: if you want to avoid macOS Keychain prompts during these runs, set `GOG_KEYRING_BACKEND=file` and `GOG_KEYRING_PASSWORD=...` (uses encrypted on-disk keyring). +Tip: if you want to avoid macOS Keychain prompts during these runs, set +`GOG_KEYRING_BACKEND=file` and inject `GOG_KEYRING_PASSWORD` from a secret store +or temporary shell session (uses encrypted on-disk keyring). ### Live Test Script (CLI) diff --git a/docs/README.md b/docs/README.md index 49faed1..6ba4be0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,9 @@ Keep, and related agent workflows. accounts, or Workspace domain-wide delegation. - Read [Command Guards and Baked Safety Profiles](safety-profiles.md) when running `gog` from agents or automation. +- Read the bundled [`gog` agent skill](../.agents/skills/gog/SKILL.md) when an + agent needs safe auth preflight, JSON-first output, or guarded Workspace + automation patterns. - Read [Sheets Tables](sheets-tables.md) when creating or inspecting Google Sheets structured tables. - Open the [Command Index](commands/README.md) for generated docs for every CLI