diff --git a/CHANGELOG.md b/CHANGELOG.md index e1e1e83d7..3fb74c563 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - API: add Discovery-backed `api list`, `api describe`, and scoped `api call` access for Google methods outside the first-class command surface, with dry-run plans and explicit write opt-in. - Safety: add global `--readonly` / `GOG_READONLY=1` runtime enforcement that blocks mutating Google and Zoom API requests before dispatch while preserving read-only query POSTs and least-privilege OAuth setup. - Add schema-generated service skills and curated agent workflows for inbox triage, meeting prep, attachment archival, Drive audits, weekly digests, and contact cleanup. +- Docs: sharpen the README and overview around task-first workflows, predictable automation, identity routing, layered agent safety, and honest product boundaries. ## 0.30.0 - 2026-06-21 diff --git a/README.md b/README.md index 8478cb108..cc7ef4c0f 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,49 @@ -# gogcli +# gog — Google Workspace from the terminal ![gogcli banner](docs/assets/readme-banner.jpg) -`gog` is a script-friendly Google CLI for Gmail, Calendar, Drive, Docs, Sheets, -Sites, Slides, Forms, Meet, Apps Script, Analytics, Search Console, Contacts, -Tasks, People, Classroom, Chat, YouTube, and Workspace admin flows. - -It is built for terminals, shell scripts, CI, and coding agents: - -- predictable `--json` and `--plain` output on stdout -- human hints and progress on stderr -- multiple Google accounts and OAuth clients -- OAuth, direct access tokens, ADC, and Workspace service accounts -- runtime command allowlists/denylists and baked safety-profile binaries -- typed [MCP server](docs/mcp.md) for agent clients, read-only by default and - without a generic command runner -- read-only audit/reporting commands for risky surfaces like Drive and Contacts -- [generated docs](docs/commands/README.md) for every command - -Rendered docs: - -Start here: - -- [Install](docs/install.md) -- [Quickstart](docs/quickstart.md) -- [Auth clients and service accounts](docs/auth-clients.md) -- [MCP server](docs/mcp.md) -- [Agent skills](docs/agent-skills.md) -- [Command index](docs/commands/README.md) -- [Gmail watch / Pub/Sub push](docs/watch.md) () +One binary. Task-first commands. Predictable automation. + +`gog` gives people, scripts, CI, and coding agents one CLI for Gmail, Calendar, +Drive, Docs, Sheets, Slides, Forms, Meet, Apps Script, Analytics, Search +Console, Contacts, Tasks, Classroom, Chat, YouTube, and Workspace admin. + +```bash +# Find mail, inspect today's calendar, and audit a Drive folder. +gog --account you@gmail.com --readonly gmail search 'is:unread newer_than:7d' --max 10 +gog --account you@gmail.com --readonly calendar events --today +gog --account you@gmail.com --readonly drive audit sharing --parent --json + +# Make automation parseable, non-interactive, read-only, and unable to send Gmail. +gog --readonly --gmail-no-send --no-input --json gmail search 'label:inbox' +``` + +## Why gog + +Google APIs expose resources and methods. Real work crosses them. `gog` keeps +the raw capability, then adds the workflow and operational contracts a durable +CLI needs: + +- **Task-first workflows:** search and sanitize mail, resolve calendar names, + audit Drive sharing, edit Docs, append Sheet tables, build Slides, manage + Workspace users, and back up accounts. +- **Automation that composes:** stable `--json` and `--plain` stdout; prompts, + progress, and warnings on stderr; documented exit codes; `--no-input` for CI. +- **Many identities, one install:** account aliases, named OAuth clients, direct + access tokens, ADC, OS/encrypted-file keyrings, and Workspace service accounts. +- **Agent safety with explicit boundaries:** runtime `--readonly`, command + allow/deny rules, `--gmail-no-send`, untrusted-content wrapping, dry-run plans, + baked safety-profile binaries, and a typed MCP server that is read-only by default. +- **A discoverable contract:** `gog schema --json`, generated reference pages + for every command, and schema-generated service skills for agent workflows. + +Read [Why gog](docs/why-gog.md) for the design tradeoffs, or go straight to: +[Install](docs/install.md) · [Quickstart](docs/quickstart.md) · [Auth](docs/auth-clients.md) · +[Command index](docs/commands/README.md) · [Automation](docs/automation.md) · +[Agent skills](docs/agent-skills.md) · [MCP](docs/mcp.md). + +Rendered docs: . `gog` is open source and not affiliated +with Google. ## Install diff --git a/docs/index.md b/docs/index.md index 570237dcd..34fef8210 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,14 +39,19 @@ gog slides create-from-markdown "Weekly update" --content-file slides.md - **Stable output.** `--json` for scripts, `--plain` TSV for `awk`, human output on stderr. - **Runtime discovery.** `gog schema --json` exposes command shape, stable exit codes, output modes, and effective safety state. - **Multi-account, multi-client.** Many Google accounts and OAuth client projects in one config; OAuth, direct access tokens, ADC, and Workspace service accounts all supported. -- **One automation contract.** Humans, scripts, CI, and agents use the same commands, with JSON/TSV output, non-interactive operation, stable exit codes, untrusted-content wrapping, runtime command guards, and baked safety profiles. +- **One automation contract.** Humans, scripts, CI, and agents use the same commands, with JSON/TSV output, non-interactive operation, stable exit codes, runtime read-only enforcement, untrusted-content wrapping, command guards, and baked safety profiles. - **Preview-first audits.** Drive `tree`, `du`, `inventory`; Contacts `dedupe` previews by default and requires explicit `--apply` for guarded merges; raw API JSON dumps never mutate remote state. -- **Generated reference.** Every command has a docs page produced from `gog schema --json`. +- **Generated reference.** Every command has a docs page, and service-level agent skills are generated from the same `gog schema --json` contract. + +The short version is in [Why gog](why-gog.md): workflow-first commands, stdout +as an API, identity routing, layered safety, and a contract generated from the +live binary. ## Pick your path - **Trying it.** [Install](install.md) → [Quickstart](quickstart.md). Five minutes from `brew install` to your first authenticated query. -- **Wiring up automation.** [Automation](automation.md), [Safety Profiles](safety-profiles.md), and the bundled [`gog` skill](https://github.com/openclaw/gogcli/blob/main/.agents/skills/gog/SKILL.md). Discover the active contract and lock the binary down before handing it to an untrusted caller. +- **Understanding the design.** [Why gog](why-gog.md) explains what the project optimizes for and where its boundaries are. +- **Wiring up automation.** [Automation](automation.md), [Safety Profiles](safety-profiles.md), and [Agent skills](agent-skills.md). Discover the active contract and lock the binary down before handing it to an untrusted caller. - **Serving MCP tools.** [MCP server](mcp.md) exposes typed, allowlisted tools for agent clients without a generic command bridge. - **Discovering runtime contracts.** [Automation](automation.md) explains root help, schema metadata, safety controls, and stable exit codes. - **Polling local events.** [Drive and Docs polling](polling.md) persists cursors and optionally invokes trusted shell hooks. diff --git a/docs/why-gog.md b/docs/why-gog.md new file mode 100644 index 000000000..82221294c --- /dev/null +++ b/docs/why-gog.md @@ -0,0 +1,96 @@ +--- +title: Why gog +description: "Why gog combines task-first Google Workspace workflows with stable automation and explicit agent safety." +--- + +# Why gog + +Google Workspace automation usually starts simple: list messages, fetch an +event, update a cell. It becomes operational software as soon as it must choose +an account, preserve machine-readable output, recover from expired auth, avoid +an accidental send, or hand fetched content to an agent. + +`gog` is built for that second stage. + +## The product idea + +Use one command surface everywhere: + +```text +person at a terminal → shell script / CI → coding agent / MCP client + same gog commands +``` + +The interface does not fork into a human CLI and an agent API. Commands expose +the same arguments and behavior; global contracts make them safe to compose. + +## Five design choices + +### 1. Workflows before endpoint spelling + +First-class commands encode the parts that raw API calls leave to every user: +calendar-name resolution, pagination, time parsing, Gmail content sanitation, +Drive audit projections, Docs revision controls, dry-run plans, and stable +output shapes. + +### 2. Stdout is an API + +`--json` and `--plain` keep stdout parseable. Human guidance, warnings, +prompts, and progress use stderr. Stable exit codes let automation branch on +auth, permission, quota, empty-result, not-found, and retryable failures without +matching prose. + +### 3. Auth is a routing problem + +One installation can hold several Google accounts and several OAuth client +projects. Aliases, domain mappings, direct access tokens, ADC, and Workspace +service accounts all resolve through the same command layer. + +### 4. Safety is layered + +No single switch covers every caller. gog combines: + +- preview/dry-run behavior for mutations; +- confirmation for destructive operations; +- runtime `--readonly` enforcement before API requests are dispatched; +- Gmail no-send policy at flag, config, and account level; +- runtime command allowlists and denylists; +- baked binaries whose blocked commands disappear from help and schema; +- untrusted-content markers for fetched Google text; +- a typed MCP tool surface with writes disabled by default. + +### 5. The live CLI generates its contract + +`gog schema --json` is the source for the command reference and generated agent +skills. Documentation, agent discovery, and runtime policy inspection therefore +describe the binary that is actually running, including build-time safety +filtering. + +## Who it is for + +- People who manage more than one Google account from a terminal. +- Teams that need auditable Workspace automation in shell or CI. +- Maintainers who want high-level workflows without hiding the underlying IDs, + scopes, and API errors. +- Agent builders who need constrained tools and machine-readable contracts. + +It is not a hosted integration platform, a replacement for Google Cloud Console +administration, or a promise that every Google API feature has a curated command. +The [command index](commands/) is the exact current surface. + +## A useful first proof + +After [Quickstart](quickstart.md), run a read-only loop before enabling any +mutation workflow: + +```bash +gog auth doctor --check +gog --account you@gmail.com --readonly gmail search 'newer_than:7d' --max 5 --json +gog --account you@gmail.com --readonly calendar events --today --json +gog --account you@gmail.com --readonly drive audit sharing --parent --json +gog schema gmail search --json +``` + +Then choose the narrowest next boundary: keep runtime read-only enforcement, +add an exact command allowlist or no-send policy, use a dedicated OAuth client +or service account, or bake a safety profile into the binary.