skills/intellectronica__agent-skills
1
0
Fork 0
mirror of https://github.com/intellectronica/agent-skills.git synced 2026-09-17 14:16:29 +08:00
Code Issues Packages Projects Releases Wiki Activity

Generate plugins from skills

Browse Source
This commit is contained in:
github-actions[bot]
2026-04-25 15:31:47 +00:00
parent b4d8fd3026
commit 730ae4640a
12 changed files with 2041 additions and 2586 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude-plugin/marketplace.json
+2 -2
View File
@@ -38,8 +38,8 @@
{
"name": "gog-cli",
"source": "./plugins/gog-cli",
"description": "This skill provides comprehensive instructions for using gogcli (gog), a fast, script-friendly CLI for Google Workspace services including Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Classroom, Contacts, Tasks, People, Groups, and Keep. This skill should be used when the user wants to interact with Google services via the command line, including reading/sending email, managing calendar events, working with Google Drive files, managing classroom courses, or any other Google Workspace operations. The skill assumes gog is installed and authorised.",
"version": "0.1.1769718127",
"description": "Use this skill whenever the user wants to operate Google Workspace from the command line with gog/gogcli, including Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, auth, configuration, scripting, or agent-safe Google automation. Prefer this skill for Google account/file/mail/calendar work when the user mentions gog, gogcli, Google CLI, Gmail search/send, Calendar events, Drive files, Docs/Sheets/Slides editing, Forms, Apps Script, Workspace admin, or command-line Google automation.",
"version": "0.1.1777131088",
"category": "integrations"
},
{
plugins/gog-cli/.claude-plugin/plugin.json
+2 -2
View File
@@ -1,7 +1,7 @@
{
"name": "gog-cli",
"version": "0.1.1769718127",
"description": "This skill provides comprehensive instructions for using gogcli (gog), a fast, script-friendly CLI for Google Workspace services including Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Classroom, Contacts, Tasks, People, Groups, and Keep. This skill should be used when the user wants to interact with Google services via the command line, including reading/sending email, managing calendar events, working with Google Drive files, managing classroom courses, or any other Google Workspace operations. The skill assumes gog is installed and authorised.",
"version": "0.1.1777131088",
"description": "Use this skill whenever the user wants to operate Google Workspace from the command line with gog/gogcli, including Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, auth, configuration, scripting, or agent-safe Google automation. Prefer this skill for Google account/file/mail/calendar work when the user mentions gog, gogcli, Google CLI, Gmail search/send, Calendar events, Drive files, Docs/Sheets/Slides editing, Forms, Apps Script, Workspace admin, or command-line Google automation.",
"author": {
"name": "Eleanor Berger",
"url": "https://intellectronica.net"
plugins/gog-cli/README.md
+1 -1
View File
@@ -1,6 +1,6 @@
# gog-cli
This skill provides comprehensive instructions for using gogcli (gog), a fast, script-friendly CLI for Google Workspace services including Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Classroom, Contacts, Tasks, People, Groups, and Keep. This skill should be used when the user wants to interact with Google services via the command line, including reading/sending email, managing calendar events, working with Google Drive files, managing classroom courses, or any other Google Workspace operations. The skill assumes gog is installed and authorised.
Use this skill whenever the user wants to operate Google Workspace from the command line with gog/gogcli, including Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, auth, configuration, scripting, or agent-safe Google automation. Prefer this skill for Google account/file/mail/calendar work when the user mentions gog, gogcli, Google CLI, Gmail search/send, Calendar events, Drive files, Docs/Sheets/Slides editing, Forms, Apps Script, Workspace admin, or command-line Google automation.
## Installation
plugins/gog-cli/skills/SKILL.md
+125 -200
View File
@@ -1,255 +1,180 @@
---
name: gog-cli
description: This skill provides comprehensive instructions for using gogcli (gog), a fast, script-friendly CLI for Google Workspace services including Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, Classroom, Contacts, Tasks, People, Groups, and Keep. This skill should be used when the user wants to interact with Google services via the command line, including reading/sending email, managing calendar events, working with Google Drive files, managing classroom courses, or any other Google Workspace operations. The skill assumes gog is installed and authorised.
description: Use this skill whenever the user wants to operate Google Workspace from the command line with gog/gogcli, including Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Apps Script, Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, auth, configuration, scripting, or agent-safe Google automation. Prefer this skill for Google account/file/mail/calendar work when the user mentions gog, gogcli, Google CLI, Gmail search/send, Calendar events, Drive files, Docs/Sheets/Slides editing, Forms, Apps Script, Workspace admin, or command-line Google automation.
---
# gogcli (gog) CLI
# gogcli (gog)
A fast, script-friendly CLI for Google Workspace services with JSON-first output and multi-account support.
`gog` is a fast, script-friendly CLI for Google services. It is JSON-first, supports multiple accounts/OAuth clients, and has explicit guardrails for agent and CI usage.
**Repository**: https://github.com/steipete/gogcli
Authoritative upstream: https://github.com/steipete/gogcli
## Prerequisites
This skill was refreshed against upstream `gog` v0.13.0 (2026-04-20). When exact syntax matters, run `gog <command> --help` or `gog schema --json`; the command surface moves quickly, rather inconveniently for anyone fond of stale notes.
This skill assumes `gog` is installed and authorised. If commands fail with authentication errors, inform the user they need to:
1. **Install gog**: `brew install steipete/tap/gogcli`
2. **Store OAuth credentials**: `gog auth credentials <path-to-credentials.json>`
3. **Add account**: `gog auth add user@gmail.com --services all`
## Operating rules
Do not attempt to resolve authentication issues automatically. Provide the user with the relevant command and let them handle it.
- Prefer `gog --json ... | jq ...` for inspection and scripting.
- Use `--plain` only when stable TSV is more convenient than JSON.
- Use `--dry-run` for supported mutating operations when preparing a change or when user intent is ambiguous.
- Use `--no-input` in automation so commands fail instead of prompting.
- Use `--force` only when the user asked for the destructive/public/send/admin operation or after you have clearly explained the effect.
- Do not repair OAuth, consent, keyring, or Workspace delegation problems silently. Show the exact command the user should run.
- Do not export tokens, print secrets, open public shares, add delegates/forwarding, send mail, suspend users, or permanently delete data unless the user explicitly requested that action.
- For agent runs that must not send mail, add `--gmail-no-send`, set `GOG_GMAIL_NO_SEND=1`, or configure `gog config no-send set <account>`.
## Supported Services
Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat (Workspace), Classroom, Contacts, Tasks, People, Groups (Workspace), Keep (Workspace, service account only).
## Quick Reference
### Global Flags
## Install and auth
```bash
--account <email> # Select account
--client <name> # Select OAuth client
--json # JSON output
--plain # TSV output (for scripting)
--force # Skip confirmations
--no-input # Fail instead of prompting
brew install gogcli
gog auth credentials set ~/Downloads/client_secret_....json
gog auth add you@example.com --services gmail,calendar,drive
gog auth list --check
```
### Common Patterns
Notes:
- Homebrew now uses `brew install gogcli`; old tap examples are obsolete.
- `gog auth add` defaults to `--services user`. Request the services needed for the task.
- `--services all` is accepted only as a backwards-compatible alias for `user`; do not use it when you need every API.
- Use `--readonly`, `--drive-scope readonly|file|full`, and `--gmail-scope readonly|full` for least privilege.
- Keep and Admin require Workspace service-account/domain-wide delegation. Google Chat, Groups, directory, and Classroom also have Workspace restrictions.
- For headless/CI, consider `--manual`, `--remote`, `--access-token`, or `GOG_AUTH_MODE=adc`.
Read `references/authentication.md` for full auth patterns.
## Global flags
```bash
gog --account work@example.com gmail search "is:unread" # Use specific account
gog gmail search "is:unread" --json | jq '.threads[].id' # JSON for parsing
gog gmail search "is:unread" --plain | cut -f1 # Plain for shell
gog gmail search "is:unread" --max 10 --page <token> # Pagination
--account, -a <email|alias|auto> # account selection
--client <name> # named OAuth client/token bucket
--access-token <token> # direct short-lived token; also GOG_ACCESS_TOKEN
--json, -j # machine-readable JSON
--plain, -p # stable TSV
--results-only # JSON primary result only
--select <fields> # best-effort JSON projection
--dry-run, -n # preview supported writes
--force, -y # skip confirmations
--no-input # never prompt
--enable-commands <csv> # allowlist top-level or dotted commands
--disable-commands <csv> # denylist top-level or dotted commands
--gmail-no-send # block Gmail send operations
--verbose, -v # debug logging
```
## Gmail
### Search and Read
Useful command aliases:
```bash
gog gmail search "is:unread from:boss@example.com newer_than:7d"
gog gmail messages search "is:unread" --include-body
gog gmail thread get <threadId>
gog gmail get <messageId> --format full
gog send ... # alias for gog gmail send
gog ls # alias for gog drive ls
gog search "budget" # alias for gog drive search
gog download <fileId> # alias for gog drive download
gog upload ./file.pdf # alias for gog drive upload
gog me # alias for gog people me
gog status # alias for gog auth status
gog open <id-or-url> # best-effort Google web URL, offline
```
### Send Email
## High-value workflows
### Account selection
```bash
# Basic send
gog gmail send --to user@example.com --subject "Hello" --body "Message"
# With HTML and attachments
gog gmail send --to user@example.com --subject "Report" \
--body-html "<h1>Report</h1>" --attach ~/report.pdf
# Reply
gog gmail send --to user@example.com --subject "Re: Original" \
--body "Reply" --reply-to-message-id <messageId>
gog auth alias set work you@company.com
gog --account work gmail search 'is:unread newer_than:2d'
GOG_ACCOUNT=work gog calendar events primary --today
gog --client work auth credentials set ~/Downloads/work-client.json
gog --client work auth add you@company.com --services gmail,calendar
```
### Labels
### Gmail
```bash
gog gmail labels list
gog gmail labels create "Project/Subproject"
gog gmail thread modify <threadId> --add "Label" --remove INBOX
gog --json gmail search 'is:unread newer_than:7d' | jq -r '.threads[].id'
gog gmail messages search 'from:alice@example.com has:attachment' --include-body
gog gmail messages search 'subject:report newer_than:30d' --full
gog gmail thread get <threadId> --download --out-dir ./attachments
gog gmail labels modify <threadId> --add Project --remove INBOX
gog gmail messages modify <messageId> --add STARRED
gog gmail send --to user@example.com --subject "Hello" --body-file ./body.txt
gog gmail forward <messageId> --to user@example.com --note "FYI"
```
For full Gmail reference including drafts, filters, vacation, delegates, tracking, and watch, see `references/gmail.md`.
For forwarding, autoreply, watch/Pub/Sub, filters, delegates, send-as, label colours, batch operations, and tracking, read `references/gmail.md`.
## Calendar
### Events
### Calendar
```bash
gog calendar events primary --from "2024-12-01" --to "2024-12-31" --weekday
gog calendar events primary --query "meeting"
# Create event
gog calendar create primary --summary "Meeting" \
--from "2024-12-20T14:00:00" --to "2024-12-20T15:00:00"
# With attendees and recurrence
gog calendar create primary --summary "Weekly Standup" \
--from "2024-12-20T09:00:00" --to "2024-12-20T09:30:00" \
--attendees "alice@example.com,bob@example.com" \
--rrule "FREQ=WEEKLY;BYDAY=MO,WE,FR"
# Respond
gog calendar respond primary <eventId> --status accepted
gog calendar calendars
gog calendar events primary --today --weekday
gog calendar events --all --from "2026-04-25T00:00:00+02:00" --to "2026-04-26T00:00:00+02:00"
gog calendar freebusy --cal primary --from "2026-04-25T09:00:00+02:00" --to "2026-04-25T17:00:00+02:00"
gog calendar create primary --summary "Planning" --from "2026-04-25T14:00:00+02:00" --to "2026-04-25T14:30:00+02:00" --attendees "alice@example.com,bob@example.com" --with-meet
gog calendar respond primary <eventId> --status accepted --send-updates all
```
### Special Event Types
Use RFC3339 with timezone offsets for generated datetimes. Read `references/calendar.md` for aliases, subscriptions, secondary calendars, extended properties, Focus Time, OOO, working locations, team calendars, and conflict detection.
### Drive, Docs, Sheets, Slides, Forms, Apps Script
```bash
gog calendar focus-time create primary --from DT --to DT --auto-decline
gog calendar ooo create primary --from DT --to DT --decline-message "Away"
gog calendar working-location create primary --from DT --to DT --location home
gog drive search "invoice filetype:pdf" --max 20
gog drive upload ./report.md --convert-to doc --parent <folderId>
gog drive upload ./deck.pdf --replace <fileId> --name "Board Deck.pdf"
gog drive share <fileId> --to user --email editor@example.com --role commenter
gog docs write <docId> --file ./brief.md --replace --markdown
gog docs sed <docId> 's/status/{b c=green}approved/g' --dry-run
gog sheets update <spreadsheetId> 'Sheet1!A1' '[["Name","Score"],["Ada",98]]'
gog sheets chart list <spreadsheetId>
gog slides thumbnail <presentationId> <slideId> --out ./slide.png
gog forms responses list <formId> --max 20
gog appscript run <scriptId> myFunction --params '["arg1", 123]'
```
For full Calendar reference, see `references/calendar.md`.
Read `references/drive-docs.md` for current file/content commands. For Docs sed formatting, read `references/sedmat.md`.
## Drive, Docs, Sheets, Slides
### Drive
```bash
gog drive ls --parent <folderId>
gog drive search "quarterly report"
gog drive download <fileId> --out ~/Downloads/
gog drive upload ~/report.pdf --parent <folderId>
gog drive mkdir "New Folder" --parent <folderId>
gog drive share <fileId> --email user@example.com --role writer
```
### Sheets
```bash
gog sheets read <spreadsheetId> "Sheet1!A1:D10"
gog sheets write <spreadsheetId> "Sheet1!A1:B2" --values '[["Name","Age"],["Alice",30]]'
gog sheets append <spreadsheetId> "Sheet1!A:B" --values '[["Bob",25]]'
gog sheets format <spreadsheetId> "Sheet1!A1:D1" --bold --bg-color "#FFCC00"
```
### Export
```bash
gog docs export <documentId> --format pdf --out ~/doc.pdf
gog slides export <presentationId> --format pptx --out ~/slides.pptx
```
For full Drive/Docs/Sheets/Slides reference, see `references/drive-docs.md`.
## Tasks
### Other services
```bash
gog contacts search "Ada"
gog tasks lists
gog tasks list <tasklistId>
gog tasks add <tasklistId> --title "Buy groceries" --due "2024-12-20"
gog tasks add <tasklistId> --title "Weekly review" --due "2024-12-20" --repeat weekly
gog tasks done <tasklistId> <taskId>
gog tasks add <tasklistId> --title "Weekly review" --due "2026-04-27" --repeat weekly
gog chat messages send spaces/<spaceId> --text "Build complete"
gog groups members engineering@example.com
gog admin users list --domain example.com
gog keep search "receipt"
```
## Contacts
Read `references/other-services.md` for Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, and time utilities.
## Scripting patterns
```bash
gog contacts search "john"
gog contacts create --given "John" --family "Doe" --email "john@example.com"
gog contacts directory search "smith" # Workspace
```
# Inspect shape first
gog --json gmail search 'is:unread' --max 3 | jq .
## Classroom
# Use pagination/all-pages where available
gog --json calendar events primary --from today --to tomorrow --all-pages
```bash
gog classroom courses --state ACTIVE
gog classroom students <courseId>
gog classroom coursework create <courseId> --title "Homework" --type ASSIGNMENT --due "2024-12-31T23:59:59Z"
gog classroom submissions grade <courseId> <courseworkId> <submissionId> --grade 95
```
# Fail cleanly when a supported list command has no results
gog --json calendar events primary --query "unlikely query" --fail-empty
For Classroom, Chat, Contacts, Tasks, People, Groups, Keep, see `references/other-services.md`.
## Configuration
### Config Locations
- **macOS**: `~/Library/Application Support/gogcli/config.json`
- **Linux**: `~/.config/gogcli/config.json`
- **Windows**: `%AppData%\gogcli\config.json`
### Settings
```bash
gog config set default_timezone America/New_York
gog config set default_account user@gmail.com
gog config list
```
### Environment Variables
```bash
GOG_ACCOUNT=user@gmail.com # Default account
GOG_CLIENT=work # OAuth client
GOG_JSON=1 # Default JSON output
GOG_PLAIN=1 # Default plain output
GOG_TIMEZONE=America/New_York # Display timezone
GOG_ENABLE_COMMANDS=calendar,tasks # Command allowlist
```
For full configuration, see `references/configuration.md`.
## Multi-Account Usage
```bash
gog --account work@example.com gmail search "is:unread"
gog auth alias set work work@example.com
gog --account work gmail search "is:unread"
gog auth list --check
```
For authentication including service accounts, see `references/authentication.md`.
## Scripting
```bash
# JSON processing
gog gmail search "is:unread" --json | jq -r '.threads[].id'
# Batch operations
gog gmail search "older_than:30d" --json | \
# Batch with xargs after checking output
gog --json gmail search 'older_than:1y label:newsletter' --max 200 | \
jq -r '.threads[].id' | \
xargs -I {} gog gmail thread modify {} --add Archive --remove INBOX
xargs -n 50 gog gmail labels modify --remove INBOX
# Non-interactive
gog gmail send --to user@example.com --subject "Test" --body "Hi" --force
# Agent-safe command surface
GOG_ENABLE_COMMANDS=calendar.events,calendar.freebusy,tasks \
gog --no-input --json calendar events primary --today
```
## Troubleshooting
## Reference map
If commands fail, inform the user of the likely cause:
| Error | Cause | Solution |
|-------|-------|----------|
| `no credentials` | OAuth not configured | `gog auth credentials <file>` |
| `token expired` | Auth invalid | `gog auth add <email> --force-consent` |
| `insufficient scope` | Missing permissions | `gog auth add <email> --services <services>` |
| `command not found` | Not installed | `brew install steipete/tap/gogcli` |
Status checks:
```bash
gog auth list --check
gog auth status
```
## Reference Files
- `references/command-reference.md` - Complete command specification
- `references/authentication.md` - Auth, credentials, multi-account
- `references/configuration.md` - Config and environment variables
- `references/gmail.md` - Gmail operations
- `references/calendar.md` - Calendar operations
- `references/drive-docs.md` - Drive, Docs, Sheets, Slides
- `references/other-services.md` - Classroom, Chat, Contacts, Tasks, People, Groups, Keep
- `references/command-reference.md` - generated command index from `gog schema --json`
- `references/authentication.md` - OAuth clients, service accounts, scopes, keyrings, headless auth
- `references/configuration.md` - config keys, environment variables, output modes, safety switches
- `references/gmail.md` - Gmail search, read, send, labels, settings, watch, tracking, autoreply
- `references/calendar.md` - Calendar listing, event writes, scheduling, special events, aliases
- `references/drive-docs.md` - Drive, Docs, Sheets, Slides, Forms, Apps Script
- `references/sedmat.md` - Docs sed/formatting DSL
- `references/other-services.md` - Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep
plugins/gog-cli/skills/references/authentication.md
+170 -227
View File
@@ -1,278 +1,221 @@
# gogcli Authentication Guide
# gogcli Authentication Reference
Complete guide to authentication, credentials, and account management.
Use this when configuring accounts, diagnosing auth failures, or selecting the right credential mode.
## Credential Storage
Tokens are secured using OS-native keystores:
- **macOS**: Keychain
- **Linux**: Secret Service (GNOME Keyring, KWallet)
- **Windows**: Credential Manager
An encrypted on-disk fallback is available when native keyring is unavailable.
### Keyring Backend Configuration
## Install and credentials
```bash
# Check current backend
gog config get keyring_backend
# Force specific backend
gog config set keyring_backend keychain # macOS
gog config set keyring_backend file # Encrypted file fallback
# Environment variable override
export GOG_KEYRING_BACKEND=file
export GOG_KEYRING_PASSWORD=your-encryption-password
```
---
## OAuth Client Credentials
Before adding accounts, store OAuth client credentials from Google Cloud Console.
### Creating OAuth Credentials
1. Go to Google Cloud Console > APIs & Services > Credentials
2. Create OAuth 2.0 Client ID (Desktop application type)
3. Download the JSON credentials file
4. Enable required APIs (Gmail, Calendar, Drive, etc.) in API Library
### Storing Credentials
```bash
# Store default credentials
gog auth credentials ~/Downloads/client_secret.json
# Store from stdin
cat client_secret.json | gog auth credentials -
# Store named client (for multiple organisations)
gog --client work auth credentials ~/Downloads/work-client.json
gog --client personal auth credentials ~/Downloads/personal-client.json
# Store with domain mapping (auto-select for matching email domains)
gog --client work auth credentials ~/Downloads/work.json --domain example.com
# List stored credentials
brew install gogcli
gog auth credentials set ~/Downloads/client_secret_....json
gog auth credentials list
gog auth add you@example.com --services gmail,calendar,drive
gog auth list --check
gog auth status
```
---
OAuth client credentials must be a Google Cloud "Desktop app" client JSON. Enable only the APIs needed for the task.
## Adding Accounts
## Services and scopes
Check the live service list before prescribing scopes:
```bash
# Add account with interactive browser flow
gog auth add user@gmail.com
# Add with specific services
gog auth add user@gmail.com --services gmail,calendar,drive
# Add all available services
gog auth add user@gmail.com --services all
# Add with readonly access
gog auth add user@gmail.com --readonly
# Add with specific Drive scope
gog auth add user@gmail.com --drive-scope file # Per-file access only
gog auth add user@gmail.com --drive-scope readonly # Read-only
gog auth add user@gmail.com --drive-scope full # Full access (default)
# Browserless flow (for headless systems)
gog auth add user@gmail.com --manual
# Force new consent (re-authorise)
gog auth add user@gmail.com --force-consent
```
### Available Services
```bash
# Show available services
gog auth services
# Show as markdown
gog auth services --markdown
```
Common services:
- `user` - Basic profile info (default)
- `gmail` - Email access
- `calendar` - Calendar access
- `drive` - Google Drive
- `contacts` - Contacts and People
- `tasks` - Tasks
- `classroom` - Google Classroom
- `chat` - Google Chat (Workspace)
- `sheets` - Google Sheets
- `docs` - Google Docs
- `slides` - Google Slides
Current user-service names include:
---
## Managing Multiple Accounts
### Account Selection
```bash
# Use specific account for one command
gog --account work@example.com gmail search "is:unread"
# Set default account via environment
export GOG_ACCOUNT=work@example.com
# Set default account in config
gog config set default_account work@example.com
```text
gmail, calendar, chat, classroom, drive, docs, slides, contacts,
tasks, sheets, people, forms, appscript, ads
```
### Account Aliases
Workspace-only service-account services include:
```text
groups, keep, admin
```
Important details:
- `gog auth add` defaults to `--services user`.
- `--services all` is a backwards-compatible alias for `user`, not "every Google API".
- Docs uses Docs plus Drive scopes; Slides and Sheets also rely on Drive for copy/export flows.
- Re-run with `--force-consent` when adding services or changing scope shape and Google does not return a new refresh token.
Least-privilege examples:
```bash
# Create alias
gog auth alias set work work@example.com
gog auth alias set personal me@gmail.com
gog auth add you@example.com --services gmail --gmail-scope readonly
gog auth add you@example.com --services drive --drive-scope readonly
gog auth add you@example.com --services drive --drive-scope file
gog auth add you@example.com --services gmail,drive --readonly
gog auth add you@example.com --services gmail --extra-scopes https://www.googleapis.com/auth/gmail.labels
```
# Use alias
gog --account work gmail search "is:unread"
## OAuth clients and account selection
# List aliases
Use named clients for separate Google Cloud projects, organisations, or consent screens:
```bash
gog --client work auth credentials set ~/Downloads/work-client.json
gog --client work auth add you@company.com --services gmail,calendar
gog --client work gmail search 'is:unread'
```
Domain mapping auto-selects a client for matching account emails:
```bash
gog --client work auth credentials set ~/Downloads/work.json --domain company.com
```
Client resolution order:
1. `--client` or `GOG_CLIENT`
2. `account_clients` config mapping
3. `client_domains` config mapping
4. credentials file named after the email domain
5. `default`
Account aliases:
```bash
gog auth alias set work you@company.com
gog --account work calendar events primary --today
gog auth alias list
# Remove alias
gog auth alias unset work
```
### Client Selection
`--account auto` asks gog to use the default account or the single stored token.
## Browser, manual, remote, and proxy auth
Normal local browser flow:
```bash
# Use specific client for one command
gog --client work auth add user@example.com
# Set via environment
export GOG_CLIENT=work
# Auto-select by domain (configured during credential storage)
# Accounts at @example.com will automatically use the "work" client
gog auth add you@example.com --services gmail,calendar
```
---
## Service Accounts (Workspace)
For automated access without user interaction, use service accounts with domain-wide delegation.
### Setup
1. Create service account in Google Cloud Console
2. Enable domain-wide delegation
3. Grant required scopes in Google Workspace Admin
4. Download service account key JSON
Manual flow for headless systems:
```bash
# Configure service account for impersonation
gog auth service-account set admin@example.com --key ~/service-account.json
# Check status
gog auth service-account status
# Use impersonated account
gog --account admin@example.com gmail search "is:unread"
gog auth add you@example.com --services gmail --manual
```
### Google Keep (Workspace Only)
Keep API requires service account authentication:
Remote two-step flow:
```bash
gog auth keep user@example.com --key ~/service-account.json
gog auth add you@example.com --services gmail --remote --step 1
gog auth add you@example.com --services gmail --remote --step 2 --auth-url 'http://127.0.0.1:<port>/oauth2/callback?code=...&state=...'
```
---
## Account Status
Proxy/tunnel callback:
```bash
gog auth add you@example.com --listen-addr 0.0.0.0:8080 --redirect-host gog.example.com
gog auth manage --listen-addr 0.0.0.0:8080 --redirect-host gog.example.com
```
The redirect URI must match the OAuth client configuration.
## Direct tokens and ADC
Direct short-lived token:
```bash
gog --access-token "$(gcloud auth print-access-token)" gmail labels list
GOG_ACCESS_TOKEN="$(gcloud auth print-access-token)" gog drive ls
```
Application Default Credentials mode is useful for Workload Identity, Cloud Run, and local `gcloud` ADC flows:
```bash
GOG_AUTH_MODE=adc gog --json drive ls
```
Direct access tokens expire in about an hour and do not use stored refresh tokens.
## Keyring backend
Tokens are stored in a keyring backend:
- `auto` - platform default
- `keychain` - macOS Keychain
- `file` - encrypted on-disk store
```bash
gog auth keyring
gog auth keyring keychain
gog auth keyring file
gog auth keyring auto
```
Environment overrides:
```bash
export GOG_KEYRING_BACKEND=file
export GOG_KEYRING_PASSWORD='...'
export GOG_KEYRING_SERVICE_NAME=gogcli
```
Use `GOG_KEYRING_PASSWORD` for non-interactive file-backend runs.
## Service accounts
Workspace domain-wide delegation is required for Admin and Keep and useful for unattended Workspace automation.
Setup outline:
1. Create a Google Cloud service account.
2. Enable domain-wide delegation.
3. Enable the APIs needed.
4. Add the service account client ID and comma-separated scopes in Workspace Admin Console.
5. Store the JSON key for the impersonated subject.
```bash
gog auth service-account set admin@example.com --key ~/Downloads/service-account.json
gog auth service-account status admin@example.com
gog --account admin@example.com admin users list --domain example.com
```
Remove a key:
```bash
gog auth service-account unset admin@example.com
```
Keep can also accept per-command service-account flags:
```bash
gog keep --service-account ~/service-account.json --impersonate user@example.com list
```
## Account and token management
```bash
# List all authenticated accounts
gog auth list
# List with token validation check
gog auth list --check
# Show detailed auth status
gog auth status
# List stored tokens
gog auth remove you@example.com
gog auth credentials remove work
gog auth tokens list
gog auth tokens delete you@example.com
```
---
## Removing Accounts
Token export/import contains secrets. Do not use it unless the user explicitly requested it:
```bash
# Remove account
gog auth remove user@gmail.com
# Delete specific token
gog auth tokens delete user@gmail.com
gog auth tokens export you@example.com --out token.json
gog auth tokens import token.json
```
---
## Client Selection Hierarchy
When determining which OAuth client to use, `gog` follows this priority:
1. `--client` command flag
2. `GOG_CLIENT` environment variable
3. Account-specific mapping (`account_clients` in config)
4. Domain-based mapping (`client_domains` in config)
5. Domain-matching credentials file (`credentials-<domain>.json`)
6. Default client (`credentials.json`)
---
## Troubleshooting
### Token Expired
```bash
# Re-authenticate
gog auth add user@gmail.com --force-consent
```
### Wrong Scopes
If receiving permission errors, the token may have insufficient scopes:
```bash
# Re-add with required services
gog auth add user@gmail.com --services gmail,calendar,drive --force-consent
```
### Keyring Issues
```bash
# Check keyring backend
gog config get keyring_backend
# Force file backend
gog config set keyring_backend file
# Or use environment variable
export GOG_KEYRING_BACKEND=file
export GOG_KEYRING_PASSWORD=your-secure-password
```
### Multiple Client Confusion
```bash
# See which client is being used
gog auth status
# Explicitly specify client
gog --client work gmail search "is:unread"
```
| Symptom | Likely cause | Next command |
| --- | --- | --- |
| `no credentials` | OAuth client JSON not stored | `gog auth credentials set <client.json>` |
| `insufficient scopes` or 403 | Token lacks service/scope | `gog auth add <email> --services <service> --force-consent` |
| Keychain prompts or headless failures | Backend cannot unlock | `gog auth keyring file` plus `GOG_KEYRING_PASSWORD` |
| Wrong account/client | Alias or client auto-selection | `gog auth status`; retry with `--account` and `--client` |
| Workspace endpoint fails for Gmail.com | Consumer account unsupported | Use Workspace account/admin delegation |
plugins/gog-cli/skills/references/calendar.md
+143 -273
View File
@@ -1,361 +1,231 @@
# Calendar Operations Reference
Comprehensive guide to Google Calendar operations with `gog`.
Use this for listing calendars, events, availability, scheduling, RSVP, calendar aliases, subscriptions, secondary calendars, team calendars, and Workspace scheduling helpers.
## Listing Calendars
## Calendar discovery and aliases
```bash
# List all calendars
gog calendar calendars
# JSON output
gog calendar calendars --json
gog calendar calendars --all-pages
gog calendar alias list
gog calendar alias set team team@group.calendar.google.com
gog calendar alias unset team
gog calendar events team --today
```
## Listing Events
Subscribe to shared calendars:
```bash
# List events from primary calendar
gog calendar events primary
# List from specific calendar
gog calendar events work@group.calendar.google.com
# Filter by date range
gog calendar events primary --from 2024-12-01T00:00:00Z --to 2024-12-31T23:59:59Z
# Natural date formats also work
gog calendar events primary --from "2024-12-01" --to "2024-12-31"
# Search events
gog calendar events primary --query "meeting"
# Show weekday
gog calendar events primary --weekday
# Limit results
gog calendar events primary --max 10
# Paginate
gog calendar events primary --page <nextPageToken>
gog calendar subscribe user@example.com
gog calendar subscribe team@group.calendar.google.com --color-id 9 --selected
```
---
Create secondary calendars:
## Getting Event Details
```bash
gog calendar create-calendar "Project Calendar" \
--description "Launch planning" \
--timezone Europe/Zurich \
--location "Zurich"
```
Access control:
```bash
gog calendar acl primary
gog calendar colors
```
## Listing events
```bash
gog calendar events primary
gog calendar events primary --today --weekday
gog calendar events primary --tomorrow
gog calendar events primary --week --week-start mon
gog calendar events primary --days 14
gog calendar events primary --from "2026-04-25T00:00:00+02:00" --to "2026-04-26T00:00:00+02:00"
gog calendar events --all --from today --to tomorrow
gog calendar events --cal primary --cal team --today
gog calendar events primary --query "planning"
gog calendar events primary --private-prop-filter "source=gog"
gog calendar events primary --fields "id,summary,start,end"
```
Pagination and failure handling:
```bash
gog --json calendar events primary --today --max 10
gog --json calendar events primary --today --all-pages
gog calendar events primary --query "unlikely query" --fail-empty
```
## Event details
```bash
gog calendar event primary <eventId>
gog calendar get primary <eventId>
gog calendar search "roadmap" --from today --days 30
```
---
## Create events
## Creating Events
### Basic Event
```bash
gog calendar create primary \
--summary "Team Meeting" \
--from "2024-12-20T14:00:00" \
--to "2024-12-20T15:00:00"
```
### With Details
```bash
gog calendar create primary \
--summary "Project Review" \
--description "Quarterly review of project progress" \
--location "Conference Room A" \
--from "2024-12-20T14:00:00" \
--to "2024-12-20T15:00:00"
```
### With Attendees
Prefer explicit RFC3339 timestamps with timezone offsets.
```bash
gog calendar create primary \
--summary "Team Sync" \
--from "2024-12-20T14:00:00" \
--to "2024-12-20T15:00:00" \
--attendees "alice@example.com,bob@example.com"
--from "2026-04-25T14:00:00+02:00" \
--to "2026-04-25T14:30:00+02:00" \
--attendees "alice@example.com,bob@example.com" \
--with-meet \
--send-updates all
```
### All-Day Event
Details:
```bash
gog calendar create primary \
--summary "Project Review" \
--description "Quarterly review" \
--location "Room 3" \
--from "2026-04-25T10:00:00+02:00" \
--to "2026-04-25T11:00:00+02:00" \
--event-color 2 \
--visibility private \
--transparency busy
```
All-day:
```bash
gog calendar create primary \
--summary "Company Holiday" \
--from "2024-12-25" \
--to "2024-12-26" \
--from "2026-05-01" \
--to "2026-05-02" \
--all-day
```
### With Recurrence
Recurrence and reminders:
```bash
# Weekly meeting
gog calendar create primary \
--summary "Weekly Standup" \
--from "2024-12-20T09:00:00" \
--to "2024-12-20T09:30:00" \
--rrule "FREQ=WEEKLY;BYDAY=MO,WE,FR"
# Monthly meeting
gog calendar create primary \
--summary "Monthly Review" \
--from "2024-12-01T10:00:00" \
--to "2024-12-01T11:00:00" \
--rrule "FREQ=MONTHLY;BYMONTHDAY=1"
--from "2026-04-27T09:00:00+02:00" \
--to "2026-04-27T09:30:00+02:00" \
--rrule "RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR" \
--reminder popup:10m \
--reminder email:1d
```
### With Reminders
Extended properties and attachments:
```bash
gog calendar create primary \
--summary "Important Meeting" \
--from "2024-12-20T14:00:00" \
--to "2024-12-20T15:00:00" \
--reminders "10m,1h,1d"
--summary "Imported Event" \
--from "2026-04-25T12:00:00+02:00" \
--to "2026-04-25T13:00:00+02:00" \
--source-url "https://example.com/event" \
--source-title "Source" \
--private-prop source=gog \
--shared-prop project=alpha \
--attachment "https://drive.google.com/file/d/<fileId>/view"
```
---
## Updating Events
## Update, delete, RSVP
```bash
# Update summary
gog calendar update primary <eventId> --summary "Updated Title"
# Update time
gog calendar update primary <eventId> \
--from "2024-12-20T15:00:00" \
--to "2024-12-20T16:00:00"
# Update multiple fields
gog calendar update primary <eventId> \
--summary "New Title" \
--description "Updated description" \
--location "New Location"
# Add attendee (preserves existing)
gog calendar update primary <eventId> --add-attendee "new@example.com"
# Replace all attendees
gog calendar update primary <eventId> --from "2026-04-25T15:00:00+02:00" --to "2026-04-25T16:00:00+02:00"
gog calendar update primary <eventId> --add-attendee new@example.com
gog calendar update primary <eventId> --attendees "only@example.com"
```
---
## Deleting Events
```bash
gog calendar delete primary <eventId>
```
---
Recurring-event updates/deletes can have scope flags in current builds. Check `gog calendar update --help` and `gog calendar delete --help` before altering a series.
## Responding to Events
Respond:
```bash
# Accept invitation
gog calendar respond primary <eventId> --status accepted
# Decline
gog calendar respond primary <eventId> --status declined
# Tentative
gog calendar respond primary <eventId> --status accepted --send-updates all
gog calendar respond primary <eventId> --status tentative
# Control notification sending
gog calendar respond primary <eventId> \
--status accepted \
--send-updates all # all, none, externalOnly
gog calendar respond primary <eventId> --status declined --send-updates none
```
---
## Checking Availability
```bash
# Check free/busy for calendars
gog calendar freebusy "primary,work@group.calendar.google.com" \
--from "2024-12-20T08:00:00Z" \
--to "2024-12-20T18:00:00Z"
```
---
## Proposing Alternative Times
Propose a time:
```bash
gog calendar propose-time primary <eventId> \
--from "2024-12-21T14:00:00" \
--to "2024-12-21T15:00:00"
--from "2026-04-26T14:00:00+02:00" \
--to "2026-04-26T15:00:00+02:00"
```
---
## Special Event Types
### Focus Time
## Availability and conflicts
```bash
gog calendar focus-time create primary \
--from "2024-12-20T09:00:00" \
--to "2024-12-20T12:00:00" \
--summary "Deep Work" \
--auto-decline
gog calendar freebusy primary --from "2026-04-25T09:00:00+02:00" --to "2026-04-25T17:00:00+02:00"
gog calendar freebusy --cal primary --cal team --from "2026-04-25T09:00:00+02:00" --to "2026-04-25T17:00:00+02:00"
gog calendar freebusy --all --from "2026-04-25T09:00:00+02:00" --to "2026-04-25T17:00:00+02:00"
gog calendar conflicts --today --all
gog calendar conflicts --from today --to tomorrow --cal primary
```
### Out of Office
Workspace helpers:
```bash
gog calendar ooo create primary \
--from "2024-12-20T00:00:00" \
--to "2024-12-27T00:00:00" \
--summary "Holiday" \
--decline-message "I'm away until Dec 27"
```
### Working Location
```bash
# Office
gog calendar working-location create primary \
--from "2024-12-20T09:00:00" \
--to "2024-12-20T17:00:00" \
--location office \
--building "HQ" \
--floor "3" \
--desk "3-42"
# Home
gog calendar working-location create primary \
--from "2024-12-20T09:00:00" \
--to "2024-12-20T17:00:00" \
--location home
# Custom
gog calendar working-location create primary \
--from "2024-12-20T09:00:00" \
--to "2024-12-20T17:00:00" \
--location custom \
--custom-location "Client Site"
```
---
## Calendar Colours
```bash
gog calendar colors
```
---
## Team Calendars
```bash
# View team calendar
gog calendar team team@group.calendar.google.com
# Filter by date range
gog calendar team team@group.calendar.google.com \
--from "2024-12-01" \
--to "2024-12-31"
```
---
## Conflict Detection
```bash
gog calendar conflicts primary \
--from "2024-12-20T00:00:00Z" \
--to "2024-12-27T00:00:00Z"
```
---
## Workspace Users
```bash
# List workspace users (for scheduling)
gog calendar users
gog calendar users --max 50
gog calendar team engineering@example.com --from today --days 7
```
---
## Special event types
## Access Control
Focus Time:
```bash
# List calendar ACLs
gog calendar acl primary
gog calendar acl work@group.calendar.google.com
gog calendar focus-time primary \
--summary "Deep Work" \
--from "2026-04-25T09:00:00+02:00" \
--to "2026-04-25T12:00:00+02:00" \
--auto-decline all \
--decline-message "Focus block" \
--chat-status doNotDisturb
```
---
## Time Formats
Commands accept various time formats:
| Format | Example |
|--------|---------|
| RFC3339 | `2024-12-20T14:00:00Z` |
| RFC3339 with offset | `2024-12-20T14:00:00-05:00` |
| Date only | `2024-12-20` |
| ISO datetime | `2024-12-20T14:00:00` |
The default timezone can be configured:
Out of Office:
```bash
# Set default timezone
gog config set default_timezone America/New_York
# Or via environment
export GOG_TIMEZONE=Europe/London
# Or per-command
gog time now --timezone Asia/Tokyo
gog calendar out-of-office primary \
--from "2026-05-01T00:00:00+02:00" \
--to "2026-05-05T00:00:00+02:00" \
--auto-decline all \
--decline-message "Away until May 5"
```
---
## Scripting Examples
### Find Available Slots
Working Location:
```bash
# Get free/busy and parse with jq
gog calendar freebusy "user1@example.com,user2@example.com" \
--from "2024-12-20T08:00:00Z" \
--to "2024-12-20T18:00:00Z" \
--json | jq '.calendars'
gog calendar working-location primary --from "2026-04-25" --to "2026-04-26" --type home
gog calendar working-location primary --from "2026-04-25" --to "2026-04-26" --type office --office-label "HQ" --building-id HQ --floor-id 3 --desk-id 42
gog calendar working-location primary --from "2026-04-25" --to "2026-04-26" --type custom --custom-label "Client site"
```
### Batch Create Events
Equivalent generic event creation is also available with `--event-type focus-time|out-of-office|working-location` and related `--focus-*`, `--ooo-*`, and `--working-*` flags.
```bash
# Create events from a file
while IFS=$'\t' read -r summary from to; do
gog calendar create primary \
--summary "$summary" \
--from "$from" \
--to "$to"
done < events.tsv
```
## Time input
### Export Events
Accepted formats include:
| Kind | Example |
| --- | --- |
| RFC3339 | `2026-04-25T14:00:00Z` |
| RFC3339 with offset | `2026-04-25T14:00:00+02:00` |
| ISO offset without colon | `2026-04-25T14:00:00+0200` |
| Local datetime | `2026-04-25 14:00:00` |
| Date only | `2026-04-25` |
| Relative ranges | `today`, `tomorrow`, `monday`, `next friday` |
Generated automation should use RFC3339 with explicit timezone offsets.
```bash
# Export events to JSON
gog calendar events primary \
--from "2024-12-01" \
--to "2024-12-31" \
--json > december-events.json
```
plugins/gog-cli/skills/references/command-reference.md
+419 -673
View File
File diff suppressed because it is too large Load Diff
plugins/gog-cli/skills/references/configuration.md
+86 -181
View File
@@ -1,271 +1,176 @@
# gogcli Configuration Reference
Complete guide to configuration options and environment variables.
## Config files
## Configuration File
Configuration is stored as JSON5 in platform-specific directories:
Configuration is JSON5 in the platform config directory:
| Platform | Path |
|----------|------|
| --- | --- |
| macOS | `~/Library/Application Support/gogcli/config.json` |
| Linux | `~/.config/gogcli/config.json` |
| Windows | `%AppData%\gogcli\config.json` |
### Viewing Configuration
```bash
# Show config directory path
gog config path
# List all config values
gog config list
# Get specific value
gog config get default_timezone
# List all available keys
gog config keys
```
### Setting Configuration
```bash
# Set value
gog config set default_timezone America/New_York
# Remove value
gog config get default_timezone
gog config set default_timezone Europe/Zurich
gog config unset default_timezone
```
---
## Configuration Keys
### `keyring_backend`
Force specific credential storage backend.
## Common config keys
```bash
gog config set keyring_backend keychain # macOS Keychain
gog config set keyring_backend file # Encrypted file
gog config set keyring_backend auto # Auto-detect (default)
gog config set default_account you@example.com
gog config set default_timezone Europe/Zurich
gog auth keyring file
```
### `default_timezone`
Default timezone for time display (IANA format).
```bash
gog config set default_timezone America/New_York
gog config set default_timezone Europe/London
gog config set default_timezone UTC
```
### `default_account`
Default account when `--account` not specified.
```bash
gog config set default_account user@gmail.com
```
### `account_aliases`
Map short names to email addresses. Set via `gog auth alias` commands.
### `account_clients`
Map specific accounts to OAuth clients.
Useful structured config:
```json5
{
"account_clients": {
"work@example.com": "work",
"personal@gmail.com": "personal"
}
keyring_backend: "auto",
default_timezone: "Europe/Zurich",
default_account: "you@example.com",
account_clients: {
"you@company.com": "work",
},
client_domains: {
"company.com": "work",
},
}
```
### `client_domains`
Prefer `gog auth alias ...` and `gog --client ... auth credentials set --domain ...` over hand-editing aliases/client mappings.
Map email domains to OAuth clients (auto-selection).
## Environment variables
```json5
{
"client_domains": {
"example.com": "work",
"company.org": "enterprise"
}
}
```
---
## Environment Variables
Environment variables override configuration file values.
### Account Selection
Account/auth:
```bash
# Default account
export GOG_ACCOUNT=user@gmail.com
# OAuth client selection
export GOG_ACCOUNT=you@example.com
export GOG_CLIENT=work
export GOG_ACCESS_TOKEN="$(gcloud auth print-access-token)"
export GOG_AUTH_MODE=adc
```
### Output Format
Output:
```bash
# Default to JSON output
export GOG_JSON=1
# Default to plain/TSV output
export GOG_PLAIN=1
# Control colour output
export GOG_COLOR=auto # Auto-detect (default)
export GOG_COLOR=always # Force colours
export GOG_COLOR=never # Disable colours
# Disable colours (standard)
export GOG_COLOR=never
export NO_COLOR=1
```
### Time Settings
Time and calendar:
```bash
# Default timezone
export GOG_TIMEZONE=America/New_York
# Always show weekday in calendar output
export GOG_TIMEZONE=Europe/Zurich
export GOG_CALENDAR_WEEKDAY=1
```
### Keyring Settings
Keyring:
```bash
# Force keyring backend
export GOG_KEYRING_BACKEND=file
# Encryption password for file backend
export GOG_KEYRING_PASSWORD=your-secure-password
export GOG_KEYRING_PASSWORD='...'
export GOG_KEYRING_SERVICE_NAME=gogcli
```
### Command Allowlist
Restrict available commands (useful for sandboxed/agent execution):
Agent safety:
```bash
# Allow only calendar and tasks commands
export GOG_ENABLE_COMMANDS=calendar,tasks
# Allow Gmail read-only operations
export GOG_ENABLE_COMMANDS=gmail
export GOG_ENABLE_COMMANDS=calendar.events,calendar.freebusy,tasks
export GOG_DISABLE_COMMANDS=gmail.send,gmail.drafts.send,drive.share
export GOG_GMAIL_NO_SEND=1
```
---
## Output modes
## Output Formats
All commands support three output modes:
### Human-Friendly (Default)
Coloured tables optimised for terminal display.
Default text output is for humans. For agents and scripts, use JSON first:
```bash
gog gmail search "is:unread"
gog --json gmail search 'is:unread' | jq '.threads'
gog --json --results-only drive search "budget" | jq .
gog --json --select id,name,mimeType drive ls
```
### JSON
Machine-readable format for scripting and parsing.
Use TSV when shell tools are enough:
```bash
gog gmail search "is:unread" --json
# Or via environment
GOG_JSON=1 gog gmail search "is:unread"
gog --plain gmail search 'is:unread' | cut -f1
```
### Plain/TSV
Errors, hints, and progress are intended for stderr so stdout remains parseable.
Tab-separated values for piping to other tools.
## Pagination and empty results
List commands commonly support `--max`, `--page`, and sometimes `--all-pages` or `--all`.
```bash
gog gmail search "is:unread" --plain
# Or via environment
GOG_PLAIN=1 gog gmail search "is:unread"
gog --json gmail search 'newer_than:7d' --max 10 | jq -r '.nextPageToken'
gog --json calendar events primary --today --all-pages
gog --json calendar events primary --query "unlikely query" --fail-empty
```
---
`--fail-empty` exits with a stable non-zero code when no results are found on commands that support it.
## Pagination
## Dates and times
List commands support pagination:
Agent guidance:
- Generate RFC3339 datetimes with explicit timezone offsets for event-like fields.
- Use `YYYY-MM-DD` only for date-only fields.
- Calendar ranges also accept relative values such as `today`, `tomorrow`, `yesterday`, `monday`, and `next friday`.
Examples:
```bash
# Limit results
gog gmail search "is:unread" --max 10
# Get next page
gog gmail search "is:unread" --page <nextPageToken>
gog calendar events primary --from "2026-04-25T00:00:00+02:00" --to "2026-04-26T00:00:00+02:00"
gog calendar events primary --today
gog tasks add <tasklistId> --title "Renew" --due "2026-05-01"
```
JSON output includes pagination token:
## Safety controls
For read-only or constrained automation:
```bash
gog gmail search "is:unread" --json | jq '.nextPageToken'
GOG_ENABLE_COMMANDS=calendar.events,calendar.freebusy,drive.search \
gog --no-input --json calendar events primary --today
GOG_DISABLE_COMMANDS=gmail.send,gmail.forward,drive.share \
gog --no-input --json drive search "report"
gog --gmail-no-send gmail send --to user@example.com --subject "Test" --body "Blocked"
```
---
## Scripting Best Practices
### Use JSON Output
Per-account send guard:
```bash
# Parse with jq
gog gmail search "is:unread" --json | jq -r '.threads[].id'
gog config no-send set you@example.com
gog config no-send list
gog config no-send remove you@example.com
```
### Use Plain Output
Stable exit-code help:
```bash
# Simple field extraction
gog gmail search "is:unread" --plain | cut -f1
gog agent exit-codes
gog exit-codes
```
### Batch Operations
## Discovering current syntax
```bash
# Process multiple items
gog gmail search "is:unread" --json | \
jq -r '.threads[].id' | \
xargs -I {} gog gmail thread modify {} --add LABEL_ID
gog --help
GOG_HELP=full gog --help
gog <service> --help
gog <service> <command> --help
gog schema --json | jq .
```
### Error Handling
```bash
# Check exit codes
if gog gmail send --to user@example.com --subject "Test" --body "Hello"; then
echo "Sent successfully"
else
echo "Send failed"
fi
```
### Non-Interactive Mode
```bash
# Skip confirmations
gog gmail send --to user@example.com --subject "Test" --body "Hello" --force
# Fail instead of prompting
gog auth add user@gmail.com --no-input
```
The generated local reference is `references/command-reference.md`.
plugins/gog-cli/skills/references/drive-docs.md
+242 -285
View File
@@ -1,367 +1,324 @@
# Drive, Docs, Sheets, and Slides Reference
# Drive, Docs, Sheets, Slides, Forms, and Apps Script Reference
Comprehensive guide to Google Drive and document operations with `gog`.
Use this for Google Drive files and Google editor content operations.
## Google Drive
## Drive
### Listing Files
List/search:
```bash
# List files in root
gog drive ls
# List in specific folder
gog drive ls --parent <folderId>
# Filter with query
gog drive ls --query "mimeType='application/pdf'"
# Limit results
gog drive ls --max 20
# Paginate
gog drive ls --page <nextPageToken>
```
### Searching Files
```bash
# Text search
gog drive search "quarterly report"
# Limit results
gog drive search "budget" --max 10
```
### File Information
```bash
# Get file metadata
gog drive ls --all
gog drive ls --query "mimeType='application/pdf' and trashed=false"
gog drive search "quarterly report" --max 20
gog drive search "invoice filetype:pdf" --json
gog drive get <fileId>
# Get web URLs
gog drive url <fileId1> <fileId2>
```
### Downloading Files
Download/export:
```bash
# Download file
gog drive download <fileId>
# Specify output path
gog drive download <fileId> --out ~/Downloads/file.pdf
gog drive download <fileId> --out ./file.pdf
gog drive download <docFileId> --format pdf --out ./doc.pdf
gog drive download <sheetFileId> --format xlsx --out ./sheet.xlsx
gog drive download <slideFileId> --format pptx --out ./deck.pptx
```
### Uploading Files
Upload/create/replace:
```bash
# Upload to root
gog drive upload ~/Documents/report.pdf
# Upload with custom name
gog drive upload ~/Documents/report.pdf --name "Q4 Report.pdf"
# Upload to specific folder
gog drive upload ~/Documents/report.pdf --parent <folderId>
gog drive upload ./report.pdf --parent <folderId>
gog drive upload ./report.pdf --name "Q2 Report.pdf"
gog drive upload ./report.md --convert-to doc --parent <folderId>
gog drive upload ./data.csv --convert-to sheet
gog drive upload ./deck.pptx --convert-to slides
gog drive upload ./report.md --convert-to doc --keep-frontmatter
gog drive upload ./updated.pdf --replace <fileId> --name "Updated.pdf"
gog drive mkdir "New Folder" --parent <folderId>
```
### Creating Folders
`--replace` preserves the Drive file ID, shared link, and permissions.
File operations:
```bash
# Create folder in root
gog drive mkdir "New Folder"
# Create in specific location
gog drive mkdir "Subfolder" --parent <folderId>
```
### File Operations
```bash
# Delete file (to trash)
gog drive delete <fileId>
# Move file
gog drive copy <fileId> "Copy Name" --parent <folderId>
gog drive move <fileId> --parent <newFolderId>
# Copy file
gog drive copy <fileId>
gog drive copy <fileId> --name "Copy of File"
gog drive copy <fileId> --parent <folderId>
# Rename file
gog drive rename <fileId> "New Name"
gog drive delete <fileId>
gog drive delete <fileId> --permanent
```
### Sharing Files
Prefer normal delete, which moves to trash. Use `--permanent` only when explicitly requested.
Sharing:
```bash
# Share with anyone (link sharing)
gog drive share <fileId> --anyone --role reader
# Share with specific person
gog drive share <fileId> --email user@example.com --role writer
# Make discoverable
gog drive share <fileId> --anyone --role reader --discoverable
# List permissions
gog drive share <fileId> --to user --email user@example.com --role writer
gog drive share <fileId> --to user --email user@example.com --role commenter
gog drive share <fileId> --to domain --domain example.com --role reader
gog drive share <fileId> --to anyone --role reader
gog drive permissions <fileId>
# Remove sharing
gog drive unshare <fileId> <permissionId>
```
### Shared Drives
Public/domain sharing may prompt or require `--force`; explain the effect first.
Shared drives and comments:
```bash
# List shared drives
gog drive drives
# Search shared drives
gog drive drives --query "name contains 'Team'"
```
### Comments
```bash
# List comments
gog drive comments <fileId>
# Add comment
gog drive comments add <fileId> --content "This needs review"
# Reply to comment
gog drive comments reply <fileId> <commentId> --content "Done!"
# Resolve comment
gog drive comments resolve <fileId> <commentId>
# Delete comment
gog drive comments list <fileId>
gog drive comments get <fileId> <commentId>
gog drive comments create <fileId> "Please review"
gog drive comments update <fileId> <commentId> "Updated comment"
gog drive comments reply <fileId> <commentId> "Done"
gog drive comments delete <fileId> <commentId>
```
---
## Google Sheets
### Creating Spreadsheets
Drive query examples:
```bash
# Create empty spreadsheet
gog sheets create "Budget 2024"
# Create with named sheet
gog sheets create "Budget 2024" --sheet "Q1"
gog drive ls --query "name contains 'Report'"
gog drive ls --query "'<folderId>' in parents and trashed=false"
gog drive ls --query "mimeType='application/vnd.google-apps.spreadsheet'"
gog drive ls --query "modifiedTime > '2026-04-01T00:00:00'"
```
### Getting Spreadsheet Info
## Docs
```bash
# Get spreadsheet metadata
gog sheets get <spreadsheetId>
# Get sheet metadata
gog sheets metadata <spreadsheetId>
```
### Reading Data
```bash
# Read range
gog sheets read <spreadsheetId> "Sheet1!A1:D10"
# Read entire sheet
gog sheets read <spreadsheetId> "Sheet1"
# JSON output
gog sheets read <spreadsheetId> "Sheet1!A1:D10" --json
```
### Writing Data
```bash
# Write values (overwrites)
gog sheets write <spreadsheetId> "Sheet1!A1:B2" \
--values '[["Name","Age"],["Alice",30]]'
# Update values
gog sheets update <spreadsheetId> "Sheet1!A1:B2" \
--values '[["Name","Age"],["Bob",25]]'
```
### Appending Data
```bash
# Append rows
gog sheets append <spreadsheetId> "Sheet1!A:B" \
--values '[["Charlie",35],["Diana",28]]'
```
### Clearing Data
```bash
# Clear range
gog sheets clear <spreadsheetId> "Sheet1!A1:D10"
```
### Formatting Cells
```bash
# Bold text
gog sheets format <spreadsheetId> "Sheet1!A1:D1" --bold
# Multiple formatting options
gog sheets format <spreadsheetId> "Sheet1!A1:D1" \
--bold \
--italic \
--bg-color "#FFCC00" \
--fg-color "#000000" \
--font-size 14 \
--h-align center
# Number formatting
gog sheets format <spreadsheetId> "Sheet1!B2:B100" \
--number-format "$#,##0.00"
```
### Range Format (A1 Notation)
| Format | Description |
|--------|-------------|
| `Sheet1!A1` | Single cell |
| `Sheet1!A1:B2` | Range |
| `Sheet1!A:A` | Entire column |
| `Sheet1!1:1` | Entire row |
| `Sheet1` | Entire sheet |
| `A1:B2` | Default sheet |
---
## Google Docs
### Creating Documents
Create/copy/read/export:
```bash
gog docs create "Meeting Notes"
gog docs copy <docId> "Copy of Meeting Notes"
gog docs info <docId>
gog docs cat <docId>
gog docs cat <docId> -N
gog docs export <docId> --format pdf --out ./doc.pdf
gog docs export <docId> --format docx --out ./doc.docx
gog docs export <docId> --format md --out ./doc.md
gog docs export <docId> --format html --out ./doc.html
```
### Getting Document Info
Write/import:
```bash
gog docs get <documentId>
gog docs write <docId> --text "Plain text"
gog docs write <docId> --file ./brief.txt --replace
gog docs write <docId> --file ./brief.md --replace --markdown
gog docs write <docId> --file - --replace
gog docs write <docId> --file ./appendix.md --append --markdown
gog docs create "Brief" --file ./brief.md --pageless
```
### Exporting Documents
Tabs and structure:
```bash
# Export as PDF
gog docs export <documentId> --format pdf --out ~/Documents/notes.pdf
# Export as Word
gog docs export <documentId> --format docx --out ~/Documents/notes.docx
# Other formats
gog docs export <documentId> --format txt
gog docs export <documentId> --format html
gog docs export <documentId> --format md
gog docs list-tabs <docId>
gog docs structure <docId>
gog docs write <docId> --file ./tab.md --replace --markdown --tab-id <tabId>
```
---
## Google Slides
### Creating Presentations
Edit text:
```bash
gog slides create "Q4 Review"
gog docs find-replace <docId> "{{NAME}}" "Ada"
gog docs find-replace <docId> "{{BODY}}" --content-file ./body.md --format markdown
gog docs find-replace <docId> "{{LOGO}}" --content-file ./logo.md --format markdown --first
gog docs insert <docId> "Intro text" --index 1
gog docs delete <docId> --start 10 --end 20
gog docs clear <docId>
```
### Getting Presentation Info
Sed-style rich editing:
```bash
gog slides get <presentationId>
gog docs sed <docId> 's/status/{b c=green}approved/g' --dry-run
gog docs sed <docId> -f edits.sed
echo 's/title/{h=1}Quarterly Report/' | gog docs sed <docId>
```
### Exporting Presentations
Read `references/sedmat.md` for the full sedmat DSL: bold/italic, colours, links, images, headings, tables, checkboxes, and regex captures.
Docs comments:
```bash
# Export as PDF
gog slides export <presentationId> --format pdf --out ~/Documents/slides.pdf
# Export as PowerPoint
gog slides export <presentationId> --format pptx --out ~/Documents/slides.pptx
gog docs comments list <docId>
gog docs comments add <docId> "Please revise this paragraph"
gog docs comments reply <docId> <commentId> "Updated"
gog docs comments resolve <docId> <commentId>
gog docs comments delete <docId> <commentId>
```
---
## Sheets
## Drive Query Syntax
The `--query` parameter uses Google Drive query syntax:
| Query | Description |
|-------|-------------|
| `name = 'Report'` | Exact name match |
| `name contains 'Report'` | Name contains |
| `mimeType = 'application/pdf'` | File type |
| `'folderId' in parents` | In specific folder |
| `trashed = false` | Not in trash |
| `starred = true` | Starred files |
| `sharedWithMe = true` | Shared with me |
| `modifiedTime > '2024-01-01'` | Modified after date |
### Common MIME Types
| Type | MIME Type |
|------|-----------|
| Folder | `application/vnd.google-apps.folder` |
| Document | `application/vnd.google-apps.document` |
| Spreadsheet | `application/vnd.google-apps.spreadsheet` |
| Presentation | `application/vnd.google-apps.presentation` |
| PDF | `application/pdf` |
### Example Queries
Create/copy/export:
```bash
# PDFs only
gog drive ls --query "mimeType='application/pdf'"
# Recent files
gog drive ls --query "modifiedTime > '2024-12-01'"
# Starred spreadsheets
gog drive ls --query "starred=true and mimeType='application/vnd.google-apps.spreadsheet'"
gog sheets create "Budget 2026" --sheets "Q1,Q2"
gog sheets create "Budget 2026" --parent <folderId>
gog sheets copy <spreadsheetId> "Budget Copy"
gog sheets export <spreadsheetId> --format xlsx --out ./budget.xlsx
gog sheets metadata <spreadsheetId>
```
---
## Scripting Examples
### Backup Folder
Values:
```bash
# Download all files from a folder
gog drive ls --parent <folderId> --json | \
gog sheets get <spreadsheetId> 'Sheet1!A1:D10'
gog sheets update <spreadsheetId> 'Sheet1!A1:B2' '[["Name","Age"],["Ada",30]]'
gog sheets append <spreadsheetId> 'Sheet1!A:B' '[["Grace",35]]'
gog sheets clear <spreadsheetId> 'Sheet1!A1:D10'
```
Formatting and layout:
```bash
gog sheets format <spreadsheetId> 'Sheet1!A1:D1' --bold --bg-color '#FFCC00' --h-align center
gog sheets number-format <spreadsheetId> 'Sheet1!B2:B100' --pattern '$#,##0.00'
gog sheets merge <spreadsheetId> 'Sheet1!A1:D1'
gog sheets unmerge <spreadsheetId> 'Sheet1!A1:D1'
gog sheets freeze <spreadsheetId> --sheet Sheet1 --rows 1 --cols 0
gog sheets resize-columns <spreadsheetId> 'Sheet1!A:C' --width 160
gog sheets resize-rows <spreadsheetId> 'Sheet1!1:10' --height 36
gog sheets read-format <spreadsheetId> 'Sheet1!A1:B2'
gog sheets read-format <spreadsheetId> 'Sheet1!A1:B2' --effective
```
Rows, columns, tabs:
```bash
gog sheets insert <spreadsheetId> Sheet1 rows 2 --count 3
gog sheets insert <spreadsheetId> Sheet1 cols 3 --after
gog sheets add-tab <spreadsheetId> "Summary" --index 0
gog sheets rename-tab <spreadsheetId> "Sheet1" "Raw"
gog sheets delete-tab <spreadsheetId> "Old" --force
```
Notes, links, find/replace:
```bash
gog sheets notes <spreadsheetId> 'Sheet1!A1:B10'
gog sheets update-note <spreadsheetId> 'Sheet1!A1' --note "Check this"
gog sheets update-note <spreadsheetId> 'Sheet1!A1' --note ''
gog sheets links <spreadsheetId> 'Sheet1!A1:B10'
gog sheets find-replace <spreadsheetId> "old" "new" --sheet Sheet1
```
Named ranges:
```bash
gog sheets named-ranges list <spreadsheetId>
gog sheets named-ranges get <spreadsheetId> MyRange
gog sheets named-ranges add <spreadsheetId> MyRange 'Sheet1!A1:B2'
gog sheets named-ranges update <spreadsheetId> MyRange --name BetterRange
gog sheets named-ranges delete <spreadsheetId> BetterRange
```
Charts:
```bash
gog sheets chart list <spreadsheetId>
gog sheets chart get <spreadsheetId> <chartId> --json > chart.json
gog sheets chart create <spreadsheetId> --spec-json @chart.json --sheet Sheet1 --anchor E10
gog sheets chart update <spreadsheetId> <chartId> --spec-json '{"title":"New Title"}'
gog sheets chart delete <spreadsheetId> <chartId>
```
A1 range reminders:
| Format | Meaning |
| --- | --- |
| `Sheet1!A1` | one cell |
| `Sheet1!A1:B2` | rectangular range |
| `Sheet1!A:A` | column |
| `Sheet1!1:1` | row |
| `Sheet1` | whole sheet |
| `A1:B2` | default sheet |
## Slides
Create/copy/export:
```bash
gog slides create "Q2 Review"
gog slides copy <presentationId> "Q2 Review Copy"
gog slides info <presentationId>
gog slides export <presentationId> --format pptx --out ./deck.pptx
gog slides export <presentationId> --format pdf --out ./deck.pdf
```
Generate/edit decks:
```bash
gog slides create-from-markdown "Status Deck" --content-file ./deck.md
gog slides create-from-template <templateId> "Monthly Report" --replace "month=April" --replace "revenue=$1.2M"
gog slides create-from-template <templateId> "Monthly Report" --replacements replacements.json
gog slides add-slide <presentationId> ./slide.png --notes "Speaker notes"
gog slides replace-slide <presentationId> <slideId> ./replacement.png
gog slides update-notes <presentationId> <slideId> --notes-file ./notes.txt
```
Inspect/render:
```bash
gog slides list-slides <presentationId>
gog slides read-slide <presentationId> <slideId>
gog slides read-slide <presentationId> <slideId> --recursive --json
gog slides thumbnail <presentationId> <slideId>
gog slides thumbnail <presentationId> <slideId> --out ./slide.png
gog slides thumbnail <presentationId> <slideId> --size medium --format jpeg --out ./slide.jpg
gog slides delete-slide <presentationId> <slideId>
```
## Forms
```bash
gog forms create --title "Weekly Check-in" --description "Friday async update"
gog forms get <formId>
gog forms update <formId> --title "Weekly Sync" --quiz true
gog forms add-question <formId> --title "What shipped?" --type paragraph --required
gog forms move-question <formId> 3 1
gog forms delete-question <formId> 2 --force
gog forms responses list <formId> --max 20
gog forms responses get <formId> <responseId>
gog forms watch create <formId> --topic projects/<project>/topics/<topic>
gog forms watch list <formId>
gog forms watch renew <formId> <watchId>
gog forms watch delete <formId> <watchId>
```
## Apps Script
```bash
gog appscript create --title "Automation Helpers"
gog appscript create --title "Bound Script" --parent-id <driveFileId>
gog appscript get <scriptId>
gog appscript content <scriptId>
gog appscript run <scriptId> myFunction --params '["arg1", 123, true]'
gog appscript run <scriptId> myFunction --dev-mode
```
## Scripting examples
Download every PDF in a folder:
```bash
gog --json drive ls --parent <folderId> --query "mimeType='application/pdf'" | \
jq -r '.files[].id' | \
xargs -I {} gog drive download {} --out ~/backup/
xargs -n 1 -I {} gog drive download {} --out ./pdfs/
```
### Bulk Upload
Export all docs returned by a query:
```bash
# Upload all PDFs in directory
for f in ~/Documents/*.pdf; do
gog drive upload "$f" --parent <folderId>
done
```
### Export All Docs as PDF
```bash
gog drive ls --query "mimeType='application/vnd.google-apps.document'" --json | \
jq -r '.files[] | "\(.id) \(.name)"' | \
while read id name; do
gog docs export "$id" --format pdf --out "~/pdfs/${name}.pdf"
gog --json drive ls --query "mimeType='application/vnd.google-apps.document' and trashed=false" | \
jq -r '.files[] | @tsv "\(.id)\t\(.name)"' | \
while IFS=$'\t' read -r id name; do
gog docs export "$id" --format pdf --out "./pdfs/${name}.pdf"
done
```
plugins/gog-cli/skills/references/gmail.md
+246 -384
View File
@@ -1,414 +1,276 @@
# Gmail Operations Reference
Comprehensive guide to Gmail operations with `gog`.
Use this for Gmail search, reading, organization, sending, forwarding, autoreply, settings, watches, tracking, and batch mail workflows.
## Search Syntax
## Search syntax
Gmail search uses standard Gmail search operators:
Gmail queries use normal Gmail search operators:
| Operator | Description | Example |
|----------|-------------|---------|
| `from:` | Sender | `from:user@example.com` |
| `to:` | Recipient | `to:me` |
| `subject:` | Subject line | `subject:meeting` |
| `is:unread` | Unread messages | `is:unread` |
| `is:starred` | Starred messages | `is:starred` |
| `is:important` | Important messages | `is:important` |
| `has:attachment` | Has attachments | `has:attachment` |
| `label:` | Label name | `label:work` |
| `in:` | Location | `in:inbox`, `in:sent`, `in:trash` |
| `after:` | Date filter | `after:2024/01/01` |
| `before:` | Date filter | `before:2024/12/31` |
| `newer_than:` | Relative date | `newer_than:7d` |
| `older_than:` | Relative date | `older_than:1m` |
| `larger:` | Size filter | `larger:5M` |
| `smaller:` | Size filter | `smaller:1M` |
| `filename:` | Attachment name | `filename:report.pdf` |
| Operator | Example |
| --- | --- |
| sender/recipient | `from:alice@example.com`, `to:me` |
| subject/body | `subject:invoice`, `"exact phrase"` |
| state | `is:unread`, `is:starred`, `is:important` |
| labels/location | `label:Project`, `in:inbox`, `in:sent`, `in:trash` |
| attachments | `has:attachment`, `filename:pdf` |
| dates | `after:2026/04/01`, `before:2026/05/01`, `newer_than:7d`, `older_than:1m` |
| size | `larger:10M`, `smaller:1M` |
| exclusion | `-label:newsletters`, `-from:noreply@example.com` |
### Combining Operators
## Reading mail
Thread search:
```bash
# Unread from specific sender in last week
gog gmail search "is:unread from:boss@example.com newer_than:7d"
# Large attachments from anyone
gog gmail search "has:attachment larger:10M"
# Exclude certain labels
gog gmail search "is:unread -label:newsletters"
gog gmail search 'is:unread newer_than:7d'
gog --json gmail search 'from:boss@example.com has:attachment' --max 20
gog --json gmail search 'older_than:1y' --max 200 | jq -r '.threads[].id'
```
---
## Searching and Retrieving
### Search Threads
Message search:
```bash
# Basic search
gog gmail search "is:unread"
# Limit results
gog gmail search "is:unread" --max 10
# Get next page
gog gmail search "is:unread" --page <token>
# JSON output for scripting
gog gmail search "is:unread" --json
gog gmail messages search 'from:alice@example.com'
gog gmail messages search 'is:unread' --include-body
gog gmail messages search 'subject:report newer_than:30d' --full
```
### Search Messages
Retrieve:
```bash
# Search individual messages
gog gmail messages search "from:user@example.com"
# Include message body
gog gmail messages search "is:unread" --include-body
```
### Get Thread
```bash
# Get full thread
gog gmail thread get <threadId>
# Download attachments
gog gmail thread get <threadId> --download
```
### Get Message
```bash
# Get message (default format)
gog gmail get <messageId>
# Specific format
gog gmail thread get <threadId> --full
gog gmail thread get <threadId> --download --out-dir ./attachments
gog gmail get <messageId> --format full
gog gmail get <messageId> --format metadata
gog gmail get <messageId> --format metadata --headers Subject,From,Date
gog gmail get <messageId> --format raw
# Get specific headers
gog gmail get <messageId> --headers Subject,From,Date
```
### Get Attachments
```bash
# Download attachment
gog gmail attachment <messageId> <attachmentId>
# Specify output path
gog gmail attachment <messageId> <attachmentId> --out ~/Downloads/
# Specify filename
gog gmail attachment <messageId> <attachmentId> --name report.pdf
```
### Get URLs
```bash
# Get Gmail web URLs
gog gmail url <threadId1> <threadId2>
```
---
## Sending Email
### Basic Send
Attachments:
```bash
gog gmail send \
--to recipient@example.com \
--subject "Hello" \
--body "Plain text message"
gog gmail thread attachments <threadId>
gog gmail attachment <messageId> <attachmentId> --out ./attachments/
gog gmail attachment <messageId> <attachmentId> --name report.pdf
```
### HTML Body
```bash
gog gmail send \
--to recipient@example.com \
--subject "Hello" \
--body-html "<h1>Hello</h1><p>HTML message</p>"
```
### Multiple Recipients
```bash
gog gmail send \
--to user1@example.com \
--to user2@example.com \
--cc manager@example.com \
--bcc archive@example.com \
--subject "Team Update"
--body "Message to multiple recipients"
```
### Attachments
```bash
gog gmail send \
--to recipient@example.com \
--subject "Report" \
--body "Please see attached" \
--attach ~/Documents/report.pdf \
--attach ~/Documents/data.xlsx
```
### Reply to Message
```bash
gog gmail send \
--to recipient@example.com \
--subject "Re: Original Subject" \
--body "Reply content" \
--reply-to-message-id <originalMessageId>
```
### With Open Tracking
```bash
# Send with tracking (requires setup)
gog gmail send \
--to recipient@example.com \
--subject "Tracked Email" \
--body-html "<p>This email tracks opens</p>" \
--track
# Track multiple recipients separately
gog gmail send \
--to user1@example.com \
--to user2@example.com \
--subject "Tracked" \
--body-html "<p>Each recipient tracked separately</p>" \
--track-split
```
---
## Labels
### List Labels
```bash
gog gmail labels list
gog gmail labels list --json
```
### Get Label
```bash
gog gmail labels get INBOX
gog gmail labels get "Label Name"
gog gmail labels get <labelId>
```
### Create Label
```bash
gog gmail labels create "Project/SubLabel"
```
### Modify Thread Labels
```bash
# Add label
gog gmail thread modify <threadId> --add "Label Name"
# Remove label
gog gmail thread modify <threadId> --remove INBOX
# Multiple operations
gog gmail thread modify <threadId> --add Archive --remove INBOX
```
### Batch Label Modification
```bash
gog gmail labels modify <threadId1> <threadId2> --add "Done"
```
---
## Drafts
### List Drafts
```bash
gog gmail drafts list
gog gmail drafts list --max 10
```
### Create Draft
```bash
gog gmail drafts create \
--to recipient@example.com \
--subject "Draft Subject" \
--body "Draft content"
```
### Update Draft
```bash
gog gmail drafts update <draftId> \
--subject "Updated Subject" \
--body "Updated content"
```
### Send Draft
```bash
gog gmail drafts send <draftId>
```
### Delete Draft
```bash
gog gmail drafts delete <draftId>
```
---
## Settings
### Autoforward
```bash
gog gmail autoforward status
gog gmail autoforward enable forward@example.com
gog gmail autoforward disable
```
### Delegates
```bash
gog gmail delegates list
gog gmail delegates add assistant@example.com
gog gmail delegates remove assistant@example.com
```
### Filters
```bash
# List filters
gog gmail filters list
# Get filter
gog gmail filters get <filterId>
# Delete filter
gog gmail filters delete <filterId>
```
### Vacation Responder
```bash
# Check status
gog gmail vacation status
# Enable
gog gmail vacation enable \
--subject "Out of Office" \
--body "I am currently away..." \
--from "2024-12-20T00:00:00Z" \
--to "2024-12-27T00:00:00Z"
# Disable
gog gmail vacation disable
```
### Send-As Addresses
```bash
gog gmail sendas list
gog gmail sendas get alias@example.com
```
---
## Email Tracking
### Setup Tracking
```bash
# Configure tracking worker URL
gog gmail track setup --worker-url https://your-worker.workers.dev
```
### Check Status
```bash
gog gmail track status
```
### View Opens
```bash
# By tracking ID
gog gmail track opens --id <trackingId>
# By recipient
gog gmail track opens --recipient user@example.com
```
---
## Watch (Pub/Sub Notifications)
### Start Watching
```bash
# Watch all labels
gog gmail watch start --topic projects/my-project/topics/gmail-notifications
# Watch specific labels
gog gmail watch start \
--topic projects/my-project/topics/gmail-notifications \
--label INBOX \
--label "Important"
```
### Check Status
```bash
gog gmail watch status
```
### Renew Watch
```bash
gog gmail watch renew
```
### Stop Watching
```bash
gog gmail watch stop
```
### Run Handler Server
```bash
gog gmail watch serve \
--bind 0.0.0.0 \
--port 8080 \
--path /webhook
# Include message body in notifications
gog gmail watch serve \
--bind 0.0.0.0 \
--port 8080 \
--path /webhook \
--include-body \
--max-bytes 20000
```
### Get History
History:
```bash
gog gmail history --since <historyId>
```
## Sending and drafts
Before sending from an agent, verify the user asked to actually send. Use `--dry-run` where possible or configure no-send guards when preparing content.
```bash
gog gmail send --to recipient@example.com --subject "Hello" --body "Plain text"
gog gmail send --to recipient@example.com --subject "Report" --body-file ./body.txt --attach ./report.pdf
gog gmail send --to user@example.com --subject "HTML" --body-html '<p>Hello</p>'
gog gmail send --to user@example.com --subject "Alias" --from alias@example.com --body-file ./body.txt
```
Replies:
```bash
gog gmail send --reply-to-message-id <messageId> --reply-all --subject "Re: Topic" --body-file ./reply.txt
gog gmail send --thread-id <threadId> --reply-all --quote --subject "Re: Topic" --body-file ./reply.txt
```
Forwarding:
```bash
gog gmail forward <messageId> --to user@example.com
gog gmail forward <messageId> --to user@example.com --note "FYI" --from alias@example.com
```
Drafts:
```bash
gog gmail drafts list --max 10
gog gmail drafts get <draftId> --download
gog gmail drafts create --to user@example.com --subject "Draft" --body-file ./draft.txt
gog gmail drafts update <draftId> --subject "Updated" --body-file ./draft.txt
gog gmail drafts send <draftId>
gog gmail drafts delete <draftId>
```
Tracking:
```bash
gog gmail track setup --worker-url https://your-worker.workers.dev
gog gmail send --to user@example.com --subject "Tracked" --body-html '<p>Hello</p>' --track
gog gmail send --to a@example.com --to b@example.com --subject "Tracked" --body-html '<p>Hello</p>' --track-split
gog gmail track status
gog gmail track opens <trackingId>
gog gmail track opens --recipient user@example.com
```
## Labels and organization
Labels:
```bash
gog gmail labels list
gog gmail labels get INBOX
gog gmail labels create "Project/Subproject"
gog gmail labels rename "Old Label" "New Label"
gog gmail labels style "Project" --text-color "#ffffff" --background-color "#16a34a"
gog gmail labels style "Project" --label-list-visibility labelShow --message-list-visibility show
gog gmail labels delete "Project/Old"
```
Thread/message label changes:
```bash
gog gmail thread modify <threadId> --add Project --remove INBOX
gog gmail labels modify <threadId1> <threadId2> --add Done --remove UNREAD
gog gmail messages modify <messageId> --add STARRED
gog gmail batch modify <messageId1> <messageId2> --remove UNREAD
```
Convenience actions:
```bash
gog gmail archive <messageId1> <messageId2>
gog gmail mark-read <messageId>
gog gmail unread <messageId>
gog gmail trash <messageId>
gog gmail batch delete <messageId1> <messageId2>
```
Use care: `batch delete` permanently deletes messages.
Batch patterns:
```bash
gog --json gmail search 'from:noreply@example.com' --max 200 | \
jq -r '.threads[].id' | \
xargs -n 50 gog gmail labels modify --remove INBOX
gog --json gmail messages search 'older_than:90d label:updates' --max 500 | \
jq -r '.messages[].id' | \
xargs -n 50 gog gmail batch modify --add UpdatesArchive --remove INBOX
```
## Autoreply
`gog gmail autoreply` is a one-shot command intended for cron/launchd or agent workflows. It replies once to matching messages, then labels them for dedupe.
```bash
gog gmail autoreply \
'to:support@example.com in:inbox -label:AutoReplied' \
--body-file ./support-autoreply.txt \
--label AutoReplied \
--archive \
--mark-read
```
Useful flags:
```bash
--max 20
--subject "Re: ..."
--body / --body-file / --body-html
--from alias@example.com
--reply-to support@example.com
--label AutoReplied
--archive
--mark-read
--skip-bulk
--allow-self
```
It adds `Auto-Submitted: auto-replied` and skips common bulk/list/auto-generated mail by default.
## Gmail settings
Most settings commands work both as `gog gmail <group> ...` and `gog gmail settings <group> ...`.
Filters:
```bash
gog gmail filters list
gog gmail filters get <filterId>
gog gmail filters create --from newsletters@example.com --add-label Newsletters --remove-label INBOX
gog gmail filters export --out filters.json
gog gmail filters delete <filterId>
```
Forwarding and auto-forward:
```bash
gog gmail forwarding list
gog gmail forwarding create forward@example.com
gog gmail forwarding delete forward@example.com
gog gmail autoforward get
gog gmail autoforward update --enabled --email forward@example.com --disposition archive
```
Delegates:
```bash
gog gmail delegates list
gog gmail delegates get assistant@example.com
gog gmail delegates add assistant@example.com
gog gmail delegates remove assistant@example.com
```
Send-as aliases:
```bash
gog gmail sendas list
gog gmail sendas get alias@example.com
gog gmail sendas create alias@example.com --display-name "Ada Example"
gog gmail sendas verify alias@example.com
gog gmail sendas update alias@example.com --reply-to support@example.com
gog gmail sendas delete alias@example.com
```
Vacation responder:
```bash
gog gmail vacation get
gog gmail vacation update --enabled --subject "Out of office" --body "Back Monday"
gog gmail vacation update --disabled
```
Settings that create forwarding, delegates, or public-ish automation may prompt or require `--force` in non-interactive contexts. Explain the effect first.
## Pub/Sub watch
```bash
gog gmail watch start --topic projects/my-project/topics/gmail-notifications
gog gmail watch start --topic projects/my-project/topics/gmail-notifications --label INBOX --label IMPORTANT
gog gmail watch status
gog gmail watch renew
gog gmail watch stop
```
Handler:
```bash
gog gmail watch serve --bind 0.0.0.0 --port 8080 --path /webhook
gog gmail watch serve --bind 0.0.0.0 --port 8080 --path /webhook --include-body --max-bytes 20000
```
Recent versions also support history-type filtering on watch serve. Check `gog gmail watch serve --help` before relying on exact flags.
## Auth/scopes
Readonly mail:
```bash
gog auth add you@example.com --services gmail --gmail-scope readonly
```
Full Gmail automation/settings:
```bash
gog auth add you@example.com --services gmail --gmail-scope full --force-consent
```
Settings commands need Gmail settings scopes. If a settings/filter/delegate command fails with insufficient scopes, re-auth with `--services gmail --force-consent`.
plugins/gog-cli/skills/references/other-services.md
+212 -358
View File
@@ -1,443 +1,297 @@
# Other Services Reference
Guide to Classroom, Chat, Contacts, Tasks, People, Groups, and Keep.
Use this for Chat, Classroom, Contacts, Tasks, People, Groups, Admin, Keep, and local time helpers.
## Google Classroom
## Chat (Workspace)
### Courses
Chat commands require Google Workspace; consumer Gmail accounts are not supported.
Spaces:
```bash
# List courses
gog classroom courses
gog classroom courses --state ACTIVE
gog classroom courses --state ARCHIVED
# Get course details
gog classroom courses get <courseId>
# Create course
gog classroom courses create --name "Physics 101"
gog classroom courses create --name "Physics 101" --owner me --state ACTIVE
# Update course
gog classroom courses update <courseId> --name "Physics 102"
gog classroom courses update <courseId> --state ARCHIVED
# Delete course
gog classroom courses delete <courseId>
# Archive/unarchive
gog classroom courses archive <courseId>
gog classroom courses unarchive <courseId>
# Join/leave course
gog classroom courses join <courseId> --role student
gog classroom courses leave <courseId>
# Get course URLs
gog classroom courses url <courseId1> <courseId2>
gog chat spaces list
gog chat spaces find "Engineering"
gog chat spaces find "Engineering" --exact
gog chat spaces create "Project Room" --member alice@example.com --member bob@example.com
```
### Students & Teachers
Messages and threads:
```bash
# List students
gog classroom students <courseId>
gog chat messages list spaces/<spaceId> --max 50
gog chat messages list spaces/<spaceId> --thread spaces/<spaceId>/threads/<threadId>
gog chat messages list spaces/<spaceId> --unread
gog chat messages send spaces/<spaceId> --text "Build complete"
gog chat messages send spaces/<spaceId> --text "Reply" --thread spaces/<spaceId>/threads/<threadId>
gog chat threads list spaces/<spaceId>
```
# Get student
gog classroom students get <courseId> <userId>
Reactions:
# Add student
gog classroom students add <courseId> user@example.com
gog classroom students add <courseId> user@example.com --enrollment-code CODE
```bash
gog chat messages reactions list spaces/<spaceId>/messages/<messageId>
gog chat messages react spaces/<spaceId>/messages/<messageId> <emoji>
gog chat messages reactions create spaces/<spaceId>/messages/<messageId> <emoji>
gog chat messages reactions delete spaces/<spaceId>/messages/<messageId>/reactions/<reactionId>
```
# Remove student
gog classroom students remove <courseId> <userId>
Direct messages:
# List teachers
gog classroom teachers <courseId>
```bash
gog chat dm space user@example.com
gog chat dm send user@example.com --text "Ping"
gog chat dm send user@example.com --text "Reply" --thread spaces/<spaceId>/threads/<threadId>
```
# Add/remove teachers
gog classroom teachers add <courseId> teacher@example.com
gog classroom teachers remove <courseId> <userId>
## Classroom
# Full roster
Classroom commands generally require Google Workspace for Education. Personal accounts have limited support.
Courses:
```bash
gog classroom courses list
gog classroom courses list --role teacher
gog classroom courses get <courseId>
gog classroom courses create --name "Physics 101" --owner me --state ACTIVE
gog classroom courses update <courseId> --name "Physics 102"
gog classroom courses archive <courseId>
gog classroom courses unarchive <courseId>
gog classroom courses delete <courseId>
gog classroom courses url <courseId>
```
Roster:
```bash
gog classroom roster <courseId>
gog classroom roster <courseId> --students
gog classroom roster <courseId> --teachers
gog classroom students list <courseId>
gog classroom students get <courseId> <userId>
gog classroom students add <courseId> <userId>
gog classroom students remove <courseId> <userId>
gog classroom teachers list <courseId>
gog classroom teachers add <courseId> <userId>
gog classroom teachers remove <courseId> <userId>
```
### Coursework
Coursework and materials:
```bash
# List coursework
gog classroom coursework <courseId>
gog classroom coursework <courseId> --state PUBLISHED
gog classroom coursework <courseId> --topic <topicId>
# Get coursework
gog classroom coursework list <courseId>
gog classroom coursework list <courseId> --state PUBLISHED --topic <topicId>
gog classroom coursework get <courseId> <courseworkId>
# Create assignment
gog classroom coursework create <courseId> \
--title "Homework 1" \
--description "Complete exercises 1-10" \
--type ASSIGNMENT \
--due "2024-12-31T23:59:59Z" \
--max-points 100
# Update coursework
gog classroom coursework update <courseId> <courseworkId> --title "Updated Title"
# Delete coursework
gog classroom coursework create <courseId> --title "Homework 1" --type ASSIGNMENT --state PUBLISHED --due "2026-05-01T23:59:59Z" --max-points 100
gog classroom coursework update <courseId> <courseworkId> --title "Updated"
gog classroom coursework assignees <courseId> <courseworkId> --mode INDIVIDUAL_STUDENTS --add-student <studentId>
gog classroom coursework delete <courseId> <courseworkId>
# Manage assignees
gog classroom coursework assignees <courseId> <courseworkId> --mode ALL_STUDENTS
gog classroom coursework assignees <courseId> <courseworkId> \
--mode INDIVIDUAL_STUDENTS \
--add-student user1@example.com
```
### Submissions
```bash
# List submissions
gog classroom submissions <courseId> <courseworkId>
gog classroom submissions <courseId> <courseworkId> --state TURNED_IN
# Get submission
gog classroom submissions get <courseId> <courseworkId> <submissionId>
# Turn in submission
gog classroom submissions turn-in <courseId> <courseworkId> <submissionId>
# Reclaim submission
gog classroom submissions reclaim <courseId> <courseworkId> <submissionId>
# Return submission
gog classroom submissions return <courseId> <courseworkId> <submissionId>
# Grade submission
gog classroom submissions grade <courseId> <courseworkId> <submissionId> --grade 95
```
### Materials
```bash
# List materials
gog classroom materials <courseId>
# Create/update/delete materials
gog classroom materials create <courseId> --title "Lecture Notes"
gog classroom materials update <courseId> <materialId> --title "Updated Notes"
gog classroom materials list <courseId>
gog classroom materials get <courseId> <materialId>
gog classroom materials create <courseId> --title "Syllabus" --state PUBLISHED
gog classroom materials update <courseId> <materialId> --title "Updated"
gog classroom materials delete <courseId> <materialId>
```
### Announcements
Submissions:
```bash
# List announcements
gog classroom announcements <courseId>
gog classroom submissions list <courseId> <courseworkId>
gog classroom submissions list <courseId> <courseworkId> --state TURNED_IN
gog classroom submissions get <courseId> <courseworkId> <submissionId>
gog classroom submissions grade <courseId> <courseworkId> <submissionId> --grade 95
gog classroom submissions return <courseId> <courseworkId> <submissionId>
gog classroom submissions turn-in <courseId> <courseworkId> <submissionId>
gog classroom submissions reclaim <courseId> <courseworkId> <submissionId>
```
# Create announcement
gog classroom announcements create <courseId> --text "Class cancelled tomorrow"
Announcements, topics, invitations, guardians, profile:
# Update/delete
gog classroom announcements update <courseId> <announcementId> --text "Updated text"
```bash
gog classroom announcements list <courseId>
gog classroom announcements create <courseId> --text "Welcome"
gog classroom announcements update <courseId> <announcementId> --text "Updated"
gog classroom announcements assignees <courseId> <announcementId> --mode INDIVIDUAL_STUDENTS --add-student <studentId>
gog classroom announcements delete <courseId> <announcementId>
```
### Topics
```bash
# List topics
gog classroom topics <courseId>
# Create topic
gog classroom topics list <courseId>
gog classroom topics create <courseId> --name "Unit 1"
# Update/delete
gog classroom topics update <courseId> <topicId> --name "Unit 1: Introduction"
gog classroom topics update <courseId> <topicId> --name "Unit 2"
gog classroom topics delete <courseId> <topicId>
```
### Guardians
gog classroom invitations list
gog classroom invitations create <courseId> <userId> --role student
gog classroom invitations accept <invitationId>
gog classroom invitations delete <invitationId>
```bash
# List guardians
gog classroom guardians <studentId>
# List guardian invitations
gog classroom guardian-invitations <studentId>
# Invite guardian
gog classroom guardians list <studentId>
gog classroom guardians get <studentId> <guardianId>
gog classroom guardians delete <studentId> <guardianId>
gog classroom guardian-invitations list <studentId>
gog classroom guardian-invitations create <studentId> --email parent@example.com
gog classroom profile get
gog classroom profile get <userId>
```
### Profile
## Contacts
Search/list/get:
```bash
gog classroom profile
gog classroom profile <userId>
```
---
## Google Chat (Workspace)
### Spaces
```bash
# List spaces
gog chat spaces list
# Find space by name
gog chat spaces find "Team Chat"
# Create space
gog chat spaces create "Project Discussion"
gog chat spaces create "Project Discussion" --member user1@example.com --member user2@example.com
```
### Messages
```bash
# List messages in space
gog chat messages list <spaceId>
gog chat messages list <spaceId> --max 50
gog chat messages list <spaceId> --unread
# List messages in thread
gog chat messages list <spaceId> --thread <threadId>
# Send message
gog chat messages send <spaceId> --text "Hello team!"
# Reply to thread
gog chat messages send <spaceId> --text "Reply" --thread <threadId>
```
### Threads
```bash
gog chat threads list <spaceId>
```
### Direct Messages
```bash
# Get/create DM space with user
gog chat dm space user@example.com
# Send DM
gog chat dm send user@example.com --text "Hi there!"
# Reply to DM thread
gog chat dm send user@example.com --text "Reply" --thread <threadId>
```
---
## Google Tasks
### Task Lists
```bash
# List task lists
gog tasks lists
# Create task list
gog tasks lists create "Personal"
```
### Tasks
```bash
# List tasks in list
gog tasks list <tasklistId>
# Get task
gog tasks get <tasklistId> <taskId>
# Add task
gog tasks add <tasklistId> --title "Buy groceries"
# Add task with details
gog tasks add <tasklistId> \
--title "Project deadline" \
--notes "Submit final report" \
--due "2024-12-31"
# Add repeating task
gog tasks add <tasklistId> \
--title "Weekly review" \
--due "2024-12-20" \
--repeat weekly
# Repeat options: daily, weekly, monthly, yearly
gog tasks add <tasklistId> \
--title "Monthly report" \
--due "2024-12-01" \
--repeat monthly \
--repeat-count 12 # Repeat 12 times
gog tasks add <tasklistId> \
--title "Daily standup" \
--due "2024-12-01" \
--repeat daily \
--repeat-until "2024-12-31" # Repeat until date
# Update task
gog tasks update <tasklistId> <taskId> --title "Updated title"
gog tasks update <tasklistId> <taskId> --notes "Updated notes"
gog tasks update <tasklistId> <taskId> --due "2024-12-25"
# Complete task
gog tasks done <tasklistId> <taskId>
# Uncomplete task
gog tasks undo <tasklistId> <taskId>
# Delete task
gog tasks delete <tasklistId> <taskId>
# Clear completed tasks from list
gog tasks clear <tasklistId>
```
### Subtasks
```bash
# Add subtask
gog tasks add <tasklistId> --title "Subtask" --parent <parentTaskId>
# Add after specific task
gog tasks add <tasklistId> --title "Task" --previous <previousTaskId>
```
---
## Google Contacts
### Search & List
```bash
# Search contacts
gog contacts search "john"
# List all contacts
gog contacts list
gog contacts search "Ada"
gog contacts list --max 100
gog contacts get people/c1234567890
gog contacts get ada@example.com
```
### CRUD Operations
Create/update:
```bash
# Get contact
gog contacts get people/c1234567890
gog contacts get john@example.com
gog contacts create --given "Ada" --family "Lovelace" --email ada@example.com --phone "+41441234567"
gog contacts create --given "Ada" --org "Analytical Engines Ltd" --title "Programmer" --url https://example.com --custom source=gog
gog contacts create --given "Ada" --address "street=1 Main St;city=Zurich;country=CH" --relation manager=Grace
# Create contact
gog contacts create --given "John" --family "Doe"
gog contacts create --given "John" --email "john@example.com" --phone "+1234567890"
# Update contact
gog contacts update people/c1234567890 --given "Jonathan"
gog contacts update people/c1234567890 --email "new@example.com"
# Delete contact
gog contacts update people/c1234567890 --given "Ada" --email ada@new.example
gog contacts update people/c1234567890 --birthday "1815-12-10"
gog contacts update people/c1234567890 --from-file contact.json
gog contacts update people/c1234567890 --from-file - --ignore-etag
gog contacts delete people/c1234567890
```
### Workspace Directory
Workspace directory and other contacts:
```bash
# List directory
gog contacts directory list
# Search directory
gog contacts directory search "smith"
```
### Other Contacts
```bash
# List "other contacts" (auto-added from interactions)
gog contacts other list
# Search other contacts
gog contacts other search "jane"
gog contacts other delete people/other...
```
---
For bulk or precise People API payload updates, prefer `contacts update --from-file` after inspecting `contacts get --json`.
## Google People
## Tasks
Task lists:
```bash
gog tasks lists
gog tasks lists create "Personal"
```
Tasks:
```bash
gog tasks list <tasklistId>
gog tasks get <tasklistId> <taskId>
gog tasks add <tasklistId> --title "Buy groceries"
gog tasks add <tasklistId> --title "Project deadline" --notes "Submit final report" --due "2026-05-01"
gog tasks update <tasklistId> <taskId> --title "Updated title"
gog tasks update <tasklistId> <taskId> --due ""
gog tasks done <tasklistId> <taskId>
gog tasks undo <tasklistId> <taskId>
gog tasks delete <tasklistId> <taskId>
gog tasks clear <tasklistId>
```
Repeating tasks materialize occurrences:
```bash
gog tasks add <tasklistId> --title "Weekly review" --due "2026-04-27" --repeat weekly
gog tasks add <tasklistId> --title "Monthly report" --due "2026-05-01" --repeat monthly --repeat-count 12
gog tasks add <tasklistId> --title "Daily standup" --due "2026-04-25" --repeat daily --repeat-until "2026-05-01"
gog tasks add <tasklistId> --title "Every other week" --due "2026-04-27" --recur-rrule "FREQ=WEEKLY;INTERVAL=2"
```
Subtasks/order:
```bash
gog tasks add <tasklistId> --title "Subtask" --parent <parentTaskId>
gog tasks add <tasklistId> --title "Next task" --previous <previousTaskId>
```
## People
```bash
# Get own profile
gog people me
# Get user profile
gog people get people/c1234567890
gog people get people/<userId>
gog people get user@example.com
# Search people
gog people search "john smith"
# Get relations
gog people search "Ada Lovelace" --max 5
gog people relations
gog people relations people/c1234567890 --type manager
gog people relations people/<userId> --type manager
```
---
`people search` is for Workspace directory/profile-style lookup; use `contacts search` for personal contacts.
## Google Groups (Workspace)
## Groups
Groups commands use Cloud Identity and require Workspace scopes.
```bash
# List groups
gog groups list
# Get group info
gog groups get group@example.com
# List group members
gog groups members group@example.com
gog groups members engineering@example.com
```
---
## Google Keep (Workspace Only)
Requires service account authentication.
If scopes are missing:
```bash
# List notes
gog keep list
# Get note
gog keep get <noteId>
# Create text note
gog keep create --title "Shopping List" --text "Milk, Eggs, Bread"
# Create checklist note
gog keep create --title "Todo" --list "Task 1,Task 2,Task 3"
# Delete note
gog keep delete <noteId>
gog auth add you@example.com --services groups --force-consent
```
---
## Admin (Workspace)
## Time Utilities
Admin commands require a Workspace service account with domain-wide delegation and Admin SDK scopes.
Users:
```bash
gog admin users list --domain example.com
gog admin users get user@example.com
gog admin users create user@example.com --given Ada --family Lovelace --password 'TempPass123!'
gog admin users suspend user@example.com
```
Groups:
```bash
gog admin groups list --domain example.com
gog admin groups members list engineering@example.com
gog admin groups members add engineering@example.com user@example.com --role MEMBER
gog admin groups members remove engineering@example.com user@example.com
```
Treat Admin writes as high impact. Use `--dry-run` when supported and require explicit user intent.
## Keep (Workspace)
Google Keep requires Workspace service-account access/domain-wide delegation.
```bash
gog keep --service-account ~/service-account.json --impersonate user@example.com list
gog keep --service-account ~/service-account.json --impersonate user@example.com search "receipt"
gog keep --service-account ~/service-account.json --impersonate user@example.com get <noteId>
gog keep --service-account ~/service-account.json --impersonate user@example.com create --title "Shopping" --text "Milk\nEggs"
gog keep --service-account ~/service-account.json --impersonate user@example.com create --title "Todo" --item "Task 1" --item "Task 2"
gog keep --service-account ~/service-account.json --impersonate user@example.com attachment <attachmentName> --out ./file.bin
gog keep --service-account ~/service-account.json --impersonate user@example.com delete <noteId>
```
If a service account is configured for the impersonated account, normal account selection can be enough:
```bash
gog auth service-account set user@example.com --key ~/service-account.json
gog --account user@example.com keep list
```
## Time utilities
```bash
# Get current time
gog time now
# Get time in specific timezone
gog time now --timezone UTC
gog time now --timezone Europe/Zurich
gog time now --timezone America/New_York
gog time now --timezone Europe/London
gog time now --timezone Asia/Tokyo
```
Use this for quick local/UTC conversions in scripts.
plugins/gog-cli/skills/references/sedmat.md
+393
View File
@@ -0,0 +1,393 @@
# Sedmat: Sed-like Document Formatting
**Sedmat** is a sed-inspired DSL for formatting Google Docs. It uses brace syntax `{key=value}` as its canonical format, with legacy Markdown shortcuts for convenience.
Full spec: [sedmat.org](https://sedmat.org)
```bash
gog docs sed <DOC_ID> '<expression>' # single expression
gog docs sed <DOC_ID> -f expressions.sed # batch from file
gog docs sed <DOC_ID> -f seed.txt -p # paste seed content
gog docs sed <DOC_ID> '<expr>' --dry-run # preview without applying
echo 's/foo/{b}bar/' | gog docs sed <DOC_ID> # pipe from stdin
gog docs sed <DOC_ID> <<'EOF' # heredoc
s/title/{h=t}My Report/
s/draft/{b c=green}final/
EOF
```
---
## Brace Syntax (Canonical)
The brace DSL is the primary way to format text. Braces go **before** the text by default:
```bash
s/text/{b}hello/ # braces before (default)
s/text/hello{b}/ # braces after - same result
s/text/{c=red}warning{b}/ # before and after
```
### Boolean Flags
| Key | Long | Effect |
|-----|------|--------|
| `b` | `bold` | **Bold** |
| `i` | `italic` | *Italic* |
| `_` | `underline` | Underline |
| `-` | `strike` | ~~Strikethrough~~ |
| `#` | `code` | `Monospace` (Courier New + grey bg) |
| `^` | `sup` | Superscript |
| `,` | `sub` | Subscript |
| `w` | `smallcaps` | Small Caps |
Negate with `!`: `{!b}` removes bold, `{!i}` removes italic.
```bash
s/hello/{b}hello/ # bold
s/world/{i _}world/ # italic + underline
s/note/{b i}note/ # bold + italic
s/draft/{-}draft/ # strikethrough
s/code/{#}code/ # monospace
s/TM/{^}TM/ # superscript
s/H2O/H2O - {,}2/ # subscript
s/Title/{w}Title/ # small caps
s/loud/{!b}loud/ # remove bold
```
### Key=Value Properties
| Key | Long | Value | Effect |
|-----|------|-------|--------|
| `c` | `color` | hex/name | Text color |
| `z` | `bg` | hex/name | Background/highlight |
| `f` | `font` | name | Font family |
| `s` | `size` | pt | Font size |
| `u` | `url` | URL | Hyperlink |
| `h` | `heading` | 1-6/t/s | Heading level (t=title, s=subtitle) |
| `a` | `align` | left/center/right | Paragraph alignment |
| `l` | `leading` | pt | Line spacing |
| `n` | `indent` | pt | Indentation |
| `o` | `opacity` | 0-100 | Text opacity |
| `k` | `kerning` | pt | Letter spacing |
| `p` | `spacing` | before,after | Paragraph spacing (pt) |
| `e` | `effect` | name | Text effect |
| `x` | `width` | px | Image width |
| `y` | `height` | px | Image height |
```bash
s/error/{c=red}error/ # red text
s/warning/{z=#FFFF00}warning/ # yellow highlight
s/title/{f=Georgia s=24}title/ # Georgia 24pt
s/heading/{h=2}heading/ # Heading 2
s/TITLE/{h=t}TITLE/ # Title style
s/click here/{u=https:\/\/example.com}click here/ # hyperlink
s/para/{a=center}para/ # center align
s/note/{p=12,6}note/ # 12pt before, 6pt after
s/fine/{o=50}fine/ # 50% opacity
```
### Combos
Combine any flags and properties in one brace block:
```bash
s/heading/{b f=Montserrat s=18}heading/
s/title/{h=3 f=Playfair+Display s=22 c=#333333}title/
s/link/{b i u=https:\/\/example.com}link/
```
### Clear Formatting
```bash
s/messy/{0}messy/ # strip all formatting
```
### Bookmarks & Internal Links
```bash
s/Chapter 1/{@=ch1}Chapter 1/ # create bookmark anchor
s/see chapter 1/{u=#ch1}see chapter 1/ # link to bookmark
```
---
## Structural Commands (Brace)
### Breaks
```bash
s/PAGEBREAK/{+=p}PAGEBREAK/ # page break
s/COLBREAK/{+=c}COLBREAK/ # column break
s/SECBREAK/{+=s}SECBREAK/ # section break
```
### Tables
```bash
s/placeholder/{T=4x3}placeholder/ # 4 rows x 3 cols
s/placeholder/{T=4x3:header}placeholder/ # with header row
```
### Checkboxes
```bash
s/task/{check}task/ # unchecked checkbox
s/done/{check=y}done/ # checked
s/todo/{check=n}todo/ # explicitly unchecked
```
### Images
```bash
s/placeholder/{img=https:\/\/example.com\/photo.jpg}placeholder/
s/placeholder/{img=https:\/\/example.com\/photo.jpg x=400}placeholder/
s/placeholder/{img=https:\/\/example.com\/photo.jpg x=200 y=68}placeholder/
```
---
## Legacy Markdown Syntax
Markdown shortcuts are supported for convenience. The brace syntax is preferred.
### Headings
```bash
s/text/# Heading 1/
s/text/## Heading 2/
s/text/### Heading 3/
s/text/#### Heading 4/
s/text/##### Heading 5/
s/text/###### Heading 6/
```
### Inline Styles
```bash
s/text/**bold**/
s/text/*italic*/
s/text/***bold italic***/
s/text/~~strikethrough~~/
s/text/`monospace`/
s/text/__underline__/
s/text/^{superscript}/
s/text/~{subscript}/
```
### Links & Images
```bash
s/text/[link text](https:\/\/example.com)/
s/placeholder/![alt](https:\/\/example.com\/img.png)/
s/placeholder/![alt](https:\/\/example.com\/img.png =400x200)/
```
### Lists
```bash
s/text/- bullet item/
s/text/1. numbered item/
s/text/ - nested bullet (2 spaces per level)/
s/text/- [ ] unchecked checkbox/
s/text/- [x] checked checkbox/
```
### Blocks
```bash
s/text/---/ # horizontal rule
s/text/> blockquote text/
```
### Code Blocks
````bash
s/text/```\ncode line 1\ncode line 2\n```/
````
### Footnotes
```bash
s/text/Some claim[^1]/
s/FOOTNOTE/[^1]: Source citation/
```
### Pipe Tables
```bash
s/placeholder/| Col A | Col B |\n| data1 | data2 |/
```
---
## Sed Commands
### Substitution
```bash
s/pattern/replacement/ # first match
s/pattern/replacement/g # all matches (global)
s/pattern/replacement/i # case-insensitive
s/pattern/replacement/2 # nth match only
s/pattern/replacement/m # multiline (^/$ match line boundaries)
s/pattern/replacement/gi # combine flags
```
### Delete, Append, Insert, Transliterate
```bash
d/pattern/ # delete lines matching pattern
a/pattern/new text/ # append text after matching lines
i/pattern/new text/ # insert text before matching lines
y/abc/xyz/ # transliterate a->x, b->y, c->z
```
### Back-references
```bash
s/(important)/{b}$1/ # capture + format
s/([A-Z]{2,})/{b}$1/g # bold all caps words
s/"([^"]+)"/{i}$1/g # italicize quoted text
s/hello/{b}&/ # & = whole match
```
### Positional Insert
```bash
s/^$/Initial content/ # empty doc only
s/^/Prepended text\n/ # beginning of doc
s/$/\nAppended text/ # end of doc
```
---
## Table Operations
Tables are numbered in document order (1-indexed). Use `|-1|` for last, `|*|` for all.
### Cell References
```bash
s/|1|[1,1]/{b}Header/ # row 1, col 1
s/|1|[2,3]/value/ # row 2, col 3
s/|1|[1,*]/{b}&/ # bold entire row (wildcard)
s/|1|[*,2]/data/ # set entire column
```
### Add Rows & Columns
```bash
s/|1|[+1,0]// # append row
s/|1|[0,+1]// # append column
```
### Merge & Split
```bash
s/|1|[1,1:1,3]/merge/ # merge cells row1 col1-3
s/|1|[2,2]/split/ # split merged cell
```
### Delete Tables
```bash
s/|1|// # delete first table
s/|*|// # delete all tables
```
---
## Image References
```bash
s/!(1)/!(https:\/\/new.png)/ # replace 1st image
s/!(-1)// # delete last image
s/!(*)/!(https:\/\/placeholder.png)/g # replace all images
s/![logo]/!(https:\/\/new-logo.png)/ # match by alt text
```
---
## Paragraph Addressing
Target specific paragraphs by number using address prefixes. Use `gog docs structure` to see paragraph numbers.
```bash
# Introspection - see paragraph numbers, types, and content
gog docs structure <DOC_ID> # show numbered structure
gog docs cat <DOC_ID> -N # cat with [N] prefixes
# Delete by paragraph number
gog docs sed <DOC_ID> '5d' # delete paragraph 5
gog docs sed <DOC_ID> '3,7d' # delete paragraphs 3-7
gog docs sed <DOC_ID> '$d' # delete last paragraph
# Substitute within addressed paragraphs
gog docs sed <DOC_ID> '5s/.*/New text/' # replace all text in paragraph 5
gog docs sed <DOC_ID> '3,7s/old/new/g' # replace within paragraphs 3-7
# Insert/Append around addressed paragraphs
gog docs sed <DOC_ID> '5a/New line/' # append after paragraph 5
gog docs sed <DOC_ID> '3i/Before text/' # insert before paragraph 3
gog docs sed <DOC_ID> '$a/Last line/' # append after last paragraph
```
### Address Syntax
| Address | Meaning |
|---------|---------|
| `N` | Paragraph number N (1-based) |
| `N,M` | Range from paragraph N to M |
| `$` | Last paragraph |
| `N,$` | From paragraph N to end |
### Multi-Tab Support
```bash
gog docs structure <DOC_ID> --tab "Sheet1"
gog docs sed <DOC_ID> --tab "Sheet1" '3d'
```
---
## Batch Mode
Create a `.sed` file with one expression per line. Comments start with `#`.
```bash
# format-doc.sed
s/QQQ_TITLE/{h=t}Report Title/
s/QQQ_AUTHOR/{i c=gray}John Doe/
s/QQQ_DATE/2026-02-22/
# Apply
gog docs sed <DOC_ID> -a <account> -f format-doc.sed
```
### Seed + Format Workflow
1. Clear the doc: `gog docs clear <DOC_ID> -a <account>`
2. Insert seed via positional insert: `gog docs sed <DOC_ID> -f seed.sed -a <account>`
3. Format it: `gog docs sed <DOC_ID> -f format.sed -a <account>`
---
## Options
| Flag | Effect |
|------|--------|
| `-f <file>` | Read expressions from file (batch mode) |
| `-p` | Paste mode (insert file content as text) |
| `-n` / `--dry-run` | Preview without applying changes |
| `-a <account>` | Google account to use |
---
## See Also
- `gog docs clear` - Clear all content from a document
- `gog docs edit` - Simple find/replace without regex
- `gog docs get` - Export document content
- `gog docs images list` - List images in document
- [sedmat.org](https://sedmat.org) - Full Sedmat specification