Adom Google

@@ -1,45 +1,133 @@ # adom-google -![hero](/blob/app/adom-google/docs/hero.png)+**Drive your entire Google Workspace from the terminal — and let your AI do it.** -**Your whole Google Workspace, from the terminal — for the Adom team.** One CLI that reads-and writes **Gmail, Contacts, Drive, Sheets, Docs, Slides, Calendar, and Tasks**, plus a-generic `api` passthrough to hit *any* Google API. One-click OAuth through the Adom gateway —-no per-user Google Cloud project, no copied secrets. Open source — fork it and plug in your own OAuth client.+One CLI (and one clean surface for an AI agent) that reads and writes **Gmail, Drive,+Sheets, Docs, Slides, Calendar, Tasks, Contacts, and Google Chat** — plus a generic+`api` passthrough that hits **any** Google API at all. No per-user Google Cloud project,+no client secrets copied onto anyone's machine, one consent click, and you're driving the+whole board. -## Install+> **Used every day at [Adom](https://adom.inc).** The entire Adom team runs adom-google as+> part of their daily workflow — filing quotes into Sheets, generating briefs in Docs,+> posting to Chat, dropping Calendar events, reading invoice attachments out of Gmail — all+> from the terminal and through Claude. It just works. This page is the same tool they use,+> released for everyone.++---++## Why this exists++The official Google connectors let an AI *read* your mail and calendar. They don't let it+*do the work* — create a spreadsheet, fill a doc template, build a deck, manage Drive+sharing, post to a Chat space. adom-google does, across the whole suite, with a single+token and zero per-API glue code: +```bash+adom-google api -X POST https://sheets.googleapis.com/v4/spreadsheets -d '{"properties":{"title":"BOM"}}'+adom-google api -X POST https://docs.googleapis.com/v1/documents -d '{"title":"Project brief"}'+adom-google api -X POST https://www.googleapis.com/calendar/v3/calendars/primary/events -d '{"summary":"Kickoff","start":{...},"end":{...}}'+adom-google api -X POST https://chat.googleapis.com/v1/spaces/<id>/messages -d '{"text":"shipped 🚀"}'+adom-google api  https://www.googleapis.com/drive/v3/files -q q="name contains 'invoice'"+```++That's the magic: **any Google endpoint is one `adom-google api` call away**, signed with+your token. Typed shortcuts (`gmail`, `contacts`) wrap the common flows; the passthrough+covers everything else.++---++## How the auth works (read this — it's the whole trick)++Google OAuth for a fleet of machines is normally painful: every container has a different+hostname, every user would need their own Cloud project, and the client secret would end up+copied everywhere. adom-google solves all three with a tiny **OAuth gateway service+container** that acts as a **confidential-client token broker**:++1. You run `adom-google auth`. It opens **one** Google consent screen (your own Workspace+   account). You click **Allow** once.+2. Google redirects to the gateway's single fixed callback. The **gateway** does the+   code → token exchange **and** every future refresh — because the **client secret lives+   only on the gateway**, never on your machine.+3. Your container stores just a refresh token (`0600`). It asks the gateway for fresh access+   tokens as needed. **No secret ever touches your machine, ever.**++One consent, long-lived, secret stays in exactly one hardened place. (Architecture ++source for the gateway: [`john/service-oauth`](https://wiki.adom.inc/pages/service-oauth).)++---++## Getting your own auth — three ways++The **code** is open source. The thing that's account-specific is the OAuth app + gateway.+Pick your path:++### 1. You're at Adom → just use it ```bash adompkg install adom-google-adom-google setup        # asks you: safe mode (no delete) or full mode?+adom-google setup     # asks: safe mode (no delete) or full mode?+adom-google auth      # one Allow click — done ``` -`setup` walks you through one consent click in your browser; then you're on the board.+### 2. Any other company / team → let Adom host your OAuth (easiest) 💵+Email **[email protected]**. We spin up a dedicated OAuth gateway container for your org+(~**$5/month** for the service container), wire it to a Google client for your domain, and+your whole team gets the **full adom-google capability set — exactly what the Adom team+uses every day**. You install the CLI, click Allow once, and you're driving your Workspace.+No Cloud-console wrestling, no secret management.++### 3. Self-host it → fully DIY (free, more setup)+Fork this repo and stand up your own:+- A Google Cloud project + OAuth client (Internal to your Workspace for long-lived tokens),+  with the Gmail/Drive/Sheets/Docs/Slides/Calendar/Tasks/Chat APIs enabled.+- The open-source OAuth gateway ([`john/service-oauth`](https://wiki.adom.inc/pages/service-oauth))+  on a small container, with your client's secret in `creds/<app>.json`.+- Point `OAUTH_GATEWAY_URL` + `bin/credentials.json` (client_id) at yours. -## What it does+The Chat API also needs a one-time "Chat app" configuration (name/avatar/description) in the+Cloud console — see the SKILL.md for the exact steps. -- **`adom-google api <url>`** — sign any Google REST call with your token. Create a sheet,-  fill a doc template, drop a calendar event, upload to Drive — no per-API code:-  ```bash-  adom-google api -X POST https://sheets.googleapis.com/v4/spreadsheets -d '{"properties":{"title":"BOM"}}'-  adom-google api https://www.googleapis.com/drive/v3/files -q q="name contains 'invoice'"-  ```-- **`adom-google contacts create|list|search`** — store service identities (API portals, etc.).-- **`adom-google gmail attachments|read|ics`** — pull attachment bytes + parse .ics invites.+---  ## Safe vs full mode -On first run you choose:+`adom-google setup` asks every user which scope set they want: -| Safe (default) | Full |+| **Safe** (default) | **Full** | |---|---|-| Gmail, Contacts, Calendar events, Tasks + only the Drive/Sheets/Docs/Slides files **this app creates**. **No "delete all"** on the consent screen. | Broad read/write/**delete** across **all** your existing Drive/Sheets/Docs/Slides/Calendars. |+| Read/write Gmail, Contacts, Calendar events, Tasks + only the Drive/Sheets/Docs/Slides files **this app creates**. The consent screen shows **no "see & delete ALL your files."** | Broad read/write/**delete** across **all** your existing Drive/Sheets/Docs/Slides/Calendars. For users who want the whole board. |++Each person's reach is also capped by their own Google permissions — admin APIs only work+for admins.++---++## Commands++```bash+# Generic passthrough — any Google API+adom-google api <url> [-X METHOD] [-d '<json>'|@file] [-q key=val ...]++# Contacts (People API) — store service identities, look people up+adom-google contacts create --name "..." [--org O] [--email [email protected]] [--notes "..."]+adom-google contacts list | search <query>++# Gmail (read) — attachment bytes + .ics invites the connectors can't reach+adom-google gmail attachments <messageId> | read <messageId> <attId> | ics <messageId>++adom-google status     # what's authorized (never prints secrets)+```  ## Security -- **No client secret on your container.** The Adom OAuth gateway is a confidential-client-  **token broker** — it does the code→token exchange and refresh; the secret lives only there.-- Your refresh token is stored `0600` in `~/.config/adom-google/`. Secrets are never echoed.-- Built for the Adom team, but the source is public — fork it and point it at your own gateway+client.+- **No client secret on your machine** — the gateway holds it and brokers every exchange/refresh.+- Refresh token stored `0600`; secrets are never echoed to stdout/stderr or logs.+- The gateway only ever sees a short-lived auth code or a refresh token over an authenticated+  channel — never your data.++---++Built and battle-tested at **[Adom](https://adom.inc)**. Questions, or want us to host your+org's OAuth? **[email protected]**.  > [Read the full SKILL.md source](/blob/app/adom-google/SKILL.md)