Skip to content

Commit 0122f09

Browse files
steipetesteipete
authored
feat(api): add Discovery-backed method access (#867)
* feat(api): add Discovery-backed method access * fix(api): constrain discovery calls and preserve media * fix(api): honor command policies and redirects * style(api): satisfy discovery lint checks
1 parent 635f773 commit 0122f09

15 files changed

Lines changed: 1037 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
- 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.
66
- 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.
77
- Auth: add `auth setup` for guided Google Cloud project/API preparation, OAuth client installation, and optional browser authorization.
8+
- 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.
89

910
## 0.30.0 - 2026-06-21
1011

‎README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -503,6 +503,21 @@ gog schema --json
503503
gog schema --json | jq '.automation'
504504
```
505505

506+
For APIs or methods not yet modeled as first-class commands, inspect and call
507+
Google's Discovery surface directly:
508+
509+
```bash
510+
gog api describe gmail v1 gmail.users.labels.list
511+
gog api call gmail v1 gmail.users.labels.list --params '{"userId":"me"}'
512+
```
513+
514+
Generic mutations require `--allow-write` plus confirmation (or `--force`).
515+
Prefer first-class commands when available; `api call` intentionally grants a
516+
broader surface than a narrow command allowlist. With runtime command filters,
517+
each method also needs an explicit `api.<method-id>` rule such as
518+
`api.gmail.users.labels.list`; generic calls are unavailable in binaries built
519+
with a baked safety profile.
520+
506521
There is no separate agent execution mode. The same CLI behavior serves
507522
interactive use, scripts, CI, and agents: `--json`/`--plain` keep stdout
508523
parseable, `--no-input` prevents prompts, stable exit codes classify failures,

‎docs/commands.generated.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ Generated from `gog schema --json`.
2525
- [`gog analytics (ga) <command> [flags]`](commands/gog-analytics.md) - Google Analytics
2626
- [`gog analytics (ga) accounts (list,ls) [flags]`](commands/gog-analytics-accounts.md) - List GA4 account summaries
2727
- [`gog analytics (ga) report <property> [flags]`](commands/gog-analytics-report.md) - Run a GA4 report (Analytics Data API)
28+
- [`gog api <command> [flags]`](commands/gog-api.md) - Google Discovery APIs and generic method calls
29+
- [`gog api call <api> <version> <method> [flags]`](commands/gog-api-call.md) - Call a Discovery-described API method
30+
- [`gog api describe <api> <version> [<method>]`](commands/gog-api-describe.md) - Describe a Discovery API or method
31+
- [`gog api list [flags]`](commands/gog-api-list.md) - List Google Discovery APIs
2832
- [`gog appscript (script,apps-script) <command> [flags]`](commands/gog-appscript.md) - Google Apps Script
2933
- [`gog appscript (script,apps-script) content (cat) <scriptId>`](commands/gog-appscript-content.md) - Get Apps Script project content
3034
- [`gog appscript (script,apps-script) create (new) --title=STRING [flags]`](commands/gog-appscript-create.md) - Create an Apps Script project

‎docs/commands/README.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@
22

33
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.
44

5-
Generated pages: 695.
5+
Generated pages: 699.
66

77
## Top-level Commands
88

99
- [gog admin](gog-admin.md) - Google Workspace Admin (Directory API) - requires domain-wide delegation
1010
- [gog analytics](gog-analytics.md) - Google Analytics
11+
- [gog api](gog-api.md) - Google Discovery APIs and generic method calls
1112
- [gog appscript](gog-appscript.md) - Google Apps Script
1213
- [gog auth](gog-auth.md) - Auth and credentials
1314
- [gog backup](gog-backup.md) - Encrypted Google account backups
@@ -76,6 +77,10 @@ Generated pages: 695.
7677
- [gog analytics](gog-analytics.md) - Google Analytics
7778
- [gog analytics accounts](gog-analytics-accounts.md) - List GA4 account summaries
7879
- [gog analytics report](gog-analytics-report.md) - Run a GA4 report (Analytics Data API)
80+
- [gog api](gog-api.md) - Google Discovery APIs and generic method calls
81+
- [gog api call](gog-api-call.md) - Call a Discovery-described API method
82+
- [gog api describe](gog-api-describe.md) - Describe a Discovery API or method
83+
- [gog api list](gog-api-list.md) - List Google Discovery APIs
7984
- [gog appscript](gog-appscript.md) - Google Apps Script
8085
- [gog appscript content](gog-appscript-content.md) - Get Apps Script project content
8186
- [gog appscript create](gog-appscript-create.md) - Create an Apps Script project

‎docs/commands/gog-api-call.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# `gog api call`
2+
3+
> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
4+
5+
Call a Discovery-described API method
6+
7+
## Usage
8+
9+
```bash
10+
gog api call <api> <version> <method> [flags]
11+
```
12+
13+
## Parent
14+
15+
- [gog api](gog-api.md)
16+
17+
## Flags
18+
19+
| Flag | Type | Default | Help |
20+
| --- | --- | --- | --- |
21+
| `--access-token` | `string` | | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
22+
| `-a`<br>`--account`<br>`--acct` | `string` | | Account email, alias, or auto for authenticated Google API commands |
23+
| `--allow-write` | `bool` | | Allow non-read HTTP methods (also requires confirmation or --force) |
24+
| `--body` | `string` | | JSON request body or @file |
25+
| `--client` | `string` | | OAuth client name (selects stored credentials + token bucket) |
26+
| `--color` | `string` | auto | Color output: auto\|always\|never |
27+
| `--disable-commands` | `string` | | Comma-separated list of disabled commands; dot paths allowed |
28+
| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` | | Do not make changes; print intended actions and exit successfully |
29+
| `--enable-commands` | `string` | | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
30+
| `--enable-commands-exact` | `string` | | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
31+
| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` | | Skip confirmations for destructive commands |
32+
| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
33+
| `-h`<br>`--help` | `kong.helpFlag` | | Show context-sensitive help. |
34+
| `--home` | `string` | | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
35+
| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
36+
| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` | | Never prompt; fail instead (useful for CI) |
37+
| `--params` | `string` | {} | JSON object of path and query parameters |
38+
| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
39+
| `--results-only` | `bool` | | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
40+
| `--scope` | `string` | | OAuth scope override (default: narrowest Discovery-listed scope) |
41+
| `--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. |
42+
| `-v`<br>`--verbose` | `bool` | | Enable verbose logging |
43+
| `--version` | `kong.VersionFlag` | | Print version and exit |
44+
| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
45+
46+
## See Also
47+
48+
- [gog api](gog-api.md)
49+
- [Command index](README.md)

‎docs/commands/gog-api-describe.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# `gog api describe`
2+
3+
> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
4+
5+
Describe a Discovery API or method
6+
7+
## Usage
8+
9+
```bash
10+
gog api describe <api> <version> [<method>]
11+
```
12+
13+
## Parent
14+
15+
- [gog api](gog-api.md)
16+
17+
## Flags
18+
19+
| Flag | Type | Default | Help |
20+
| --- | --- | --- | --- |
21+
| `--access-token` | `string` | | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
22+
| `-a`<br>`--account`<br>`--acct` | `string` | | Account email, alias, or auto for authenticated Google API commands |
23+
| `--client` | `string` | | OAuth client name (selects stored credentials + token bucket) |
24+
| `--color` | `string` | auto | Color output: auto\|always\|never |
25+
| `--disable-commands` | `string` | | Comma-separated list of disabled commands; dot paths allowed |
26+
| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` | | Do not make changes; print intended actions and exit successfully |
27+
| `--enable-commands` | `string` | | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
28+
| `--enable-commands-exact` | `string` | | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
29+
| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` | | Skip confirmations for destructive commands |
30+
| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
31+
| `-h`<br>`--help` | `kong.helpFlag` | | Show context-sensitive help. |
32+
| `--home` | `string` | | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
33+
| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
34+
| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` | | Never prompt; fail instead (useful for CI) |
35+
| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
36+
| `--results-only` | `bool` | | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
37+
| `--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. |
38+
| `-v`<br>`--verbose` | `bool` | | Enable verbose logging |
39+
| `--version` | `kong.VersionFlag` | | Print version and exit |
40+
| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
41+
42+
## See Also
43+
44+
- [gog api](gog-api.md)
45+
- [Command index](README.md)

‎docs/commands/gog-api-list.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# `gog api list`
2+
3+
> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
4+
5+
List Google Discovery APIs
6+
7+
## Usage
8+
9+
```bash
10+
gog api list [flags]
11+
```
12+
13+
## Parent
14+
15+
- [gog api](gog-api.md)
16+
17+
## Flags
18+
19+
| Flag | Type | Default | Help |
20+
| --- | --- | --- | --- |
21+
| `--access-token` | `string` | | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
22+
| `-a`<br>`--account`<br>`--acct` | `string` | | Account email, alias, or auto for authenticated Google API commands |
23+
| `--all` | `bool` | | Include non-preferred API versions |
24+
| `--client` | `string` | | OAuth client name (selects stored credentials + token bucket) |
25+
| `--color` | `string` | auto | Color output: auto\|always\|never |
26+
| `--disable-commands` | `string` | | Comma-separated list of disabled commands; dot paths allowed |
27+
| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` | | Do not make changes; print intended actions and exit successfully |
28+
| `--enable-commands` | `string` | | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
29+
| `--enable-commands-exact` | `string` | | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
30+
| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` | | Skip confirmations for destructive commands |
31+
| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
32+
| `-h`<br>`--help` | `kong.helpFlag` | | Show context-sensitive help. |
33+
| `--home` | `string` | | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
34+
| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
35+
| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` | | Never prompt; fail instead (useful for CI) |
36+
| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
37+
| `--results-only` | `bool` | | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
38+
| `--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. |
39+
| `-v`<br>`--verbose` | `bool` | | Enable verbose logging |
40+
| `--version` | `kong.VersionFlag` | | Print version and exit |
41+
| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
42+
43+
## See Also
44+
45+
- [gog api](gog-api.md)
46+
- [Command index](README.md)

‎docs/commands/gog-api.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# `gog api`
2+
3+
> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
4+
5+
Google Discovery APIs and generic method calls
6+
7+
## Usage
8+
9+
```bash
10+
gog api <command> [flags]
11+
```
12+
13+
## Parent
14+
15+
- [gog](gog.md)
16+
17+
## Subcommands
18+
19+
- [gog api call](gog-api-call.md) - Call a Discovery-described API method
20+
- [gog api describe](gog-api-describe.md) - Describe a Discovery API or method
21+
- [gog api list](gog-api-list.md) - List Google Discovery APIs
22+
23+
## Flags
24+
25+
| Flag | Type | Default | Help |
26+
| --- | --- | --- | --- |
27+
| `--access-token` | `string` | | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
28+
| `-a`<br>`--account`<br>`--acct` | `string` | | Account email, alias, or auto for authenticated Google API commands |
29+
| `--client` | `string` | | OAuth client name (selects stored credentials + token bucket) |
30+
| `--color` | `string` | auto | Color output: auto\|always\|never |
31+
| `--disable-commands` | `string` | | Comma-separated list of disabled commands; dot paths allowed |
32+
| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` | | Do not make changes; print intended actions and exit successfully |
33+
| `--enable-commands` | `string` | | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
34+
| `--enable-commands-exact` | `string` | | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
35+
| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` | | Skip confirmations for destructive commands |
36+
| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
37+
| `-h`<br>`--help` | `kong.helpFlag` | | Show context-sensitive help. |
38+
| `--home` | `string` | | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
39+
| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
40+
| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` | | Never prompt; fail instead (useful for CI) |
41+
| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
42+
| `--results-only` | `bool` | | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
43+
| `--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. |
44+
| `-v`<br>`--verbose` | `bool` | | Enable verbose logging |
45+
| `--version` | `kong.VersionFlag` | | Print version and exit |
46+
| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
47+
48+
## See Also
49+
50+
- [gog](gog.md)
51+
- [Command index](README.md)

‎docs/commands/gog.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ gog <command> [flags]
1818

1919
- [gog admin](gog-admin.md) - Google Workspace Admin (Directory API) - requires domain-wide delegation
2020
- [gog analytics](gog-analytics.md) - Google Analytics
21+
- [gog api](gog-api.md) - Google Discovery APIs and generic method calls
2122
- [gog appscript](gog-appscript.md) - Google Apps Script
2223
- [gog auth](gog-auth.md) - Auth and credentials
2324
- [gog backup](gog-backup.md) - Encrypted Google account backups

0 commit comments

Comments
 (0)