gog
Operate the gog CLI for Gmail, Calendar, Drive, and related Google services. Use when a user asks to run or debug gog commands, inspect flags, automate gog workflows, or validate auth/output behavior
SKILL.md.claude/skills/gog/SKILL.md
GitHubGog Skill
Use this skill to execute gog commands safely and reliably in this repo.
Preflight
- Verify binary and command tree.
./bin/gog --help
./bin/gog schema --help
- Verify config and keyring backend.
./bin/gog config path
./bin/gog auth status
./bin/gog auth keyring
- Set account explicitly for API commands.
./bin/gog --account <email> gmail --help
Auth and TTY Rules
- Prefer
--account <email>on every API command. - In this environment (
keyring_backend=file), token reads can fail in non-TTY sessions with:no TTY available for keyring file backend password prompt. - When that happens, run the command in a TTY session and submit passphrase interactively.
- If running fully non-interactive, set a usable
GOG_KEYRING_PASSWORDvalue for the configured keyring.
Output Rules
- Use
--jsonfor automation and agents. - Use
--plainfor stable TSV output. - Use rich text only for human inspection.
- Add
--no-inputin CI/automation.
Safe Execution Order
- Inspect help/schema first.
- Run read commands before write commands.
- For write commands, run
--dry-runfirst. - Use
--forceonly when the user explicitly wants to skip confirmations.
Verified Command Patterns
The following patterns were validated against ./bin/gog in this repository.
Discovery
./bin/gog gmail --help
./bin/gog calendar --help
./bin/gog drive --help
./bin/gog tasks --help
./bin/gog send --help
./bin/gog ls --help
./bin/gog open --help
Read Operations
./bin/gog --account <email> gmail labels list --plain
./bin/gog --account <email> gmail search 'newer_than:1d' --max 1 --plain
./bin/gog --account <email> calendar events primary --today --max 1 --plain
./bin/gog --account <email> drive ls --max 1 --plain
./bin/gog time now --json
Write Operation (Dry Run First)
./bin/gog --dry-run --account <email> send --to <email> --subject 'dry run test' --body 'hello' --plain
Troubleshooting
missing --account: add--account <email>or setGOG_ACCOUNT.no TTY available for keyring file backend password prompt: run in TTY or provideGOG_KEYRING_PASSWORD.unknown flag: check command-local help (./bin/gog <group> <command> --help).- Empty results should be explicit in automation: add
--fail-emptywhere supported (for examplegmail search,calendar events).
Agent Defaults
For scripted runs, prefer:
./bin/gog --account <email> --json --no-input <command...>
Then narrow payloads with command-level filters (for example --max, --fields, --query) and parse with jq only after validating output shape.