docs(skill): improve gog agent guidance (#552)
Co-authored-by: Tim Pietrusky <timpietrusky@gmail.com>
This commit is contained in:
Peter Steinberger
GitHub
parent
b836495775
commit
3ed52354a0
@ -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 <messageId> --sanitize-content --json
|
||||
gog --account user@example.com gmail thread get <threadId> --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 <documentId> --json
|
||||
gog --account user@example.com sheets get <spreadsheetId> 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 <documentId> --append --text '...'
|
||||
gog --account user@example.com sheets update <spreadsheetId> Sheet1!A1 --values-json '[["hello"]]'
|
||||
gog --account user@example.com drive upload ./file.txt --parent <folderId> --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 <service> --help
|
||||
gog <service> <command> --help
|
||||
gog schema <service> <command> --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/`
|
||||
|
||||
@ -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.
|
||||
|
||||
25
README.md
25
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)
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user