feat(auth): add guided Google setup (#865)

steipete · web-flow · commit 635f773788a8 · 2026-06-22T09:27:25.000-07:00
* feat(auth): add guided Google setup

* fix(auth): preserve client in setup guidance
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 - Evals: add reproducible structural and live Codex/OpenClaw gog/gws comparisons with correctness assertions, token/tool/latency metrics, cache-counterbalanced repetitions, methodology, and CI coverage.
 - CLI: add `GOG_HELP=agent` compact root help with common read-only recipes and targeted schema guidance so agents can execute Gmail, Calendar, and Drive tasks without traversing multiple help levels.
+- Auth: add `auth setup` for guided Google Cloud project/API preparation, OAuth client installation, and optional browser authorization.
 
 ## 0.30.0 - 2026-06-21
 
diff --git a/README.md b/README.md
@@ -607,6 +607,7 @@ Docs: [Auth clients](docs/auth-clients.md),
 Store a Desktop OAuth client once:
 
 ```bash
+gog auth setup you@gmail.com --gcloud-project my-gog-project --enable-apis --open-console
 gog auth credentials ~/Downloads/client_secret_....json
 gog auth add you@gmail.com --services gmail,calendar,drive
 ```
diff --git a/docs/commands.generated.md b/docs/commands.generated.md
@@ -52,6 +52,7 @@ Generated from `gog schema --json`.
       - [`gog auth service-account status <email>`](commands/gog-auth-service-account-status.md) - Show stored service account key status
       - [`gog auth service-account unset <email>`](commands/gog-auth-service-account-unset.md) - Remove stored service account key
     - [`gog auth services [flags]`](commands/gog-auth-services.md) - List supported auth services and scopes
+    - [`gog auth setup [<email>] [flags]`](commands/gog-auth-setup.md) - Guide Google Cloud, OAuth client, and account setup
     - [`gog auth status`](commands/gog-auth-status.md) - Show auth configuration and keyring backend
     - [`gog auth tokens <command>`](commands/gog-auth-tokens.md) - Manage stored refresh tokens
       - [`gog auth tokens delete <email>`](commands/gog-auth-tokens-delete.md) - Delete a stored refresh token
diff --git a/docs/commands/README.md b/docs/commands/README.md
@@ -2,7 +2,7 @@
 
 Every `gog` command has a generated docs page. The source of truth is the live CLI schema; run `make docs-commands` after changing command names, flags, help text, aliases, or arguments.
 
-Generated pages: 694.
+Generated pages: 695.
 
 ## Top-level Commands
 
@@ -103,6 +103,7 @@ Generated pages: 694.
       - [gog auth service-account status](gog-auth-service-account-status.md) - Show stored service account key status
       - [gog auth service-account unset](gog-auth-service-account-unset.md) - Remove stored service account key
     - [gog auth services](gog-auth-services.md) - List supported auth services and scopes
+    - [gog auth setup](gog-auth-setup.md) - Guide Google Cloud, OAuth client, and account setup
     - [gog auth status](gog-auth-status.md) - Show auth configuration and keyring backend
     - [gog auth tokens](gog-auth-tokens.md) - Manage stored refresh tokens
       - [gog auth tokens delete](gog-auth-tokens-delete.md) - Delete a stored refresh token
diff --git a/docs/commands/gog-auth-setup.md b/docs/commands/gog-auth-setup.md
@@ -0,0 +1,55 @@
+# `gog auth setup`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Guide Google Cloud, OAuth client, and account setup
+
+## Usage
+
+```bash
+gog auth setup [<email>] [flags]
+```
+
+## Parent
+
+- [gog auth](gog-auth.md)
+
+## Flags
+
+| Flag | Type | Default | Help |
+| --- | --- | --- | --- |
+| `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
+| `-a`<br>`--account`<br>`--acct` | `string` |  | Account email, alias, or auto for authenticated Google API commands |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--create-project` | `bool` |  | Create --gcloud-project with gcloud (requires confirmation) |
+| `--credentials` | `string` |  | Downloaded Desktop OAuth client JSON to store |
+| `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |
+| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` |  | Do not make changes; print intended actions and exit successfully |
+| `--enable-apis` | `bool` |  | Enable selected Google APIs with gcloud |
+| `--enable-commands` | `string` |  | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
+| `--enable-commands-exact` | `string` |  | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--force-consent` | `bool` |  | Force OAuth consent when --login runs |
+| `--gcloud-project`<br>`--project-id` | `string` |  | Google Cloud project ID (default: active gcloud project) |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `--home` | `string` |  | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--login` | `bool` |  | Run browser OAuth after project/client setup |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--open-console` | `bool` |  | Open the OAuth client page for the selected project |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--project-name` | `string` | gog CLI | Display name when creating a project |
+| `--readonly` | `bool` |  | Use read-only OAuth scopes when --login runs |
+| `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
+| `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
+| `--services` | `string` | gmail,calendar,drive,docs,sheets,contacts | Services to configure: comma-separated gmail,calendar,chat,classroom,drive,driveactivity,drivelabels,docs,slides,contacts,tasks,sheets,people,forms,sites,meet,appscript,analytics,searchconsole,ads,youtube,photos |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog auth](gog-auth.md)
+- [Command index](README.md)
diff --git a/docs/commands/gog-auth.md b/docs/commands/gog-auth.md
@@ -28,6 +28,7 @@ gog auth <command> [flags]
 - [gog auth remove](gog-auth-remove.md) - Remove a stored refresh token
 - [gog auth service-account](gog-auth-service-account.md) - Configure service account (Workspace only; domain-wide delegation)
 - [gog auth services](gog-auth-services.md) - List supported auth services and scopes
+- [gog auth setup](gog-auth-setup.md) - Guide Google Cloud, OAuth client, and account setup
 - [gog auth status](gog-auth-status.md) - Show auth configuration and keyring backend
 - [gog auth tokens](gog-auth-tokens.md) - Manage stored refresh tokens
 
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -21,6 +21,23 @@ Other options (Docker, Windows ZIPs, source builds) are documented on
 
 ## 2. Get an OAuth client
 
+For guided setup, inspect or execute the common `gcloud` path:
+
+```bash
+gog auth setup you@gmail.com --gcloud-project my-gog-project --enable-apis --open-console
+```
+
+Add `--create-project` to create that project after confirmation. After downloading the
+Desktop OAuth client JSON, one command can store it and start authorization:
+
+```bash
+gog auth setup you@gmail.com --gcloud-project my-gog-project \
+  --credentials ~/Downloads/client_secret_*.json --login
+```
+
+Use `--dry-run --json --no-input` to inspect the complete plan without creating a project,
+enabling APIs, storing credentials, opening a browser, or starting OAuth.
+
 `gog` talks to Google APIs as you, using your own Cloud project. The one-time
 setup is:
 
diff --git a/internal/cmd/auth.go b/internal/cmd/auth.go
@@ -90,6 +90,7 @@ const (
 )
 
 type AuthCmd struct {
+	Setup       AuthSetupCmd          `cmd:"" name:"setup" help:"Guide Google Cloud, OAuth client, and account setup"`
 	Credentials AuthCredentialsCmd    `cmd:"" name:"credentials" help:"Manage OAuth client credentials"`
 	Add         AuthAddCmd            `cmd:"" name:"add" help:"Authorize and store a refresh token"`
 	Import      AuthImportCmd         `cmd:"" name:"import" help:"Import a required refresh token and optional current access token non-interactively"`
diff --git a/internal/cmd/auth_setup.go b/internal/cmd/auth_setup.go
diff --git a/internal/cmd/auth_setup_test.go b/internal/cmd/auth_setup_test.go
diff --git a/internal/googleauth/service.go b/internal/googleauth/service.go

-Original file line number
+Diff line change
 Store a Desktop OAuth client once:
 ```bash
 +gog auth setup [email protected] --gcloud-project my-gog-project --enable-apis --open-console
 gog auth credentials ~/Downloads/client_secret_....json
 gog auth add [email protected] --services gmail,calendar,drive
 ```
Original file line number	Diff line number	Diff line change
`@@ -90,6 +90,7 @@ const (`
`90`	`90`	`)`
`91`	`91`
`92`	`92`	`type AuthCmd struct {`
	`93`	+ Setup AuthSetupCmd `cmd:"" name:"setup" help:"Guide Google Cloud, OAuth client, and account setup"`
`93`	`94`	Credentials AuthCredentialsCmd `cmd:"" name:"credentials" help:"Manage OAuth client credentials"`
`94`	`95`	Add AuthAddCmd `cmd:"" name:"add" help:"Authorize and store a refresh token"`
`95`	`96`	Import AuthImportCmd `cmd:"" name:"import" help:"Import a required refresh token and optional current access token non-interactively"`