feat(docs): add tab-aware raw output

steipete · steipete · commit 468e9f8c9c85 · 2026-06-10T05:19:22.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 - Gmail: report attached filenames and byte sizes in JSON results for send and draft create/update. (#716) — thanks @chrischall.
 - Gmail: add `gmail watch pull` for Pub/Sub pull subscription consumers with hook retry support. (#700) — thanks @joshp123.
+- Docs: add `--tab` and `--all-tabs` to `docs raw` for inspecting specific or complete multi-tab document content. (#697) — thanks @sebsnyk.
 
 ### Fixed
 
diff --git a/docs/commands/gog-docs-raw.md b/docs/commands/gog-docs-raw.md
@@ -20,6 +20,7 @@ gog docs (doc) raw <docId> [flags]
 | --- | --- | --- | --- |
 | `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
 | `-a`<br>`--account`<br>`--acct` | `string` |  | Account email for API commands (gmail/calendar/chat/classroom/drive/drivelabels/docs/slides/contacts/tasks/people/sheets/forms/sites/appscript/analytics/searchconsole/youtube/photos) |
+| `--all-tabs` | `bool` |  | Return the canonical Document response with all tab content populated |
 | `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
 | `--color` | `string` | auto | Color output: auto\|always\|never |
 | `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |
@@ -36,6 +37,7 @@ gog docs (doc) raw <docId> [flags]
 | `--pretty` | `bool` |  | Pretty-print JSON (default: compact single-line) |
 | `--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. |
+| `--tab` | `string` |  | Return one tab by title or ID in the legacy top-level Document shape |
 | `-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 |
diff --git a/docs/docs-editing.md b/docs/docs-editing.md
@@ -201,6 +201,11 @@ Use raw output when a script needs the Google Docs API object:
 
 ```bash
 gog docs raw <docId> --pretty
+gog docs raw <docId> --tab "Notes" --pretty
+gog docs raw <docId> --all-tabs --json
 ```
 
+`--tab` returns one tab in the same top-level Document shape used by the
+default response. `--all-tabs` returns the canonical recursive `tabs` tree.
+
 See [Raw API Dumps](raw-api.md) for lossless-output safety notes.
diff --git a/docs/raw-api.md b/docs/raw-api.md
@@ -28,10 +28,18 @@ returns it.
 ```bash
 gog drive raw <fileId> --pretty
 gog docs raw <docId> --json > doc-api.json
+gog docs raw <docId> --tab "Notes" --pretty
+gog docs raw <docId> --all-tabs --json > doc-tabs-api.json
 gog gmail raw <messageId> --format metadata --json
 gog sheets raw <spreadsheetId> --include-grid-data --json
 ```
 
+`gog docs raw --tab` resolves a tab title or ID and projects that tab into the
+legacy top-level `Document` fields such as `body`, `lists`, and
+`inlineObjects`. `--all-tabs` keeps the canonical `Documents.Get` response and
+populates its recursive `tabs` tree. Without either flag, the command keeps the
+existing first-tab response.
+
 Use service-native field masks when available:
 
 ```bash
diff --git a/internal/cmd/docs.go b/internal/cmd/docs.go
@@ -7,6 +7,7 @@ import (
 	"os"
 	"strings"
 
+	"google.golang.org/api/docs/v1"
 	"google.golang.org/api/drive/v3"
 	gapi "google.golang.org/api/googleapi"
 
@@ -68,22 +69,31 @@ type DocsTabsCmd struct {
 // REST reference: https://developers.google.com/docs/api/reference/rest/v1/documents/get
 // Go type: https://pkg.go.dev/google.golang.org/api/docs/v1#Document
 type DocsRawCmd struct {
-	DocID  string `arg:"" name:"docId" help:"Doc ID"`
-	Pretty bool   `name:"pretty" help:"Pretty-print JSON (default: compact single-line)"`
+	DocID   string `arg:"" name:"docId" help:"Doc ID"`
+	Pretty  bool   `name:"pretty" help:"Pretty-print JSON (default: compact single-line)"`
+	Tab     string `name:"tab" help:"Return one tab by title or ID in the legacy top-level Document shape"`
+	AllTabs bool   `name:"all-tabs" help:"Return the canonical Document response with all tab content populated"`
 }
 
 func (c *DocsRawCmd) Run(ctx context.Context, flags *RootFlags) error {
 	id := strings.TrimSpace(c.DocID)
 	if id == "" {
 		return usage("empty docId")
 	}
+	if strings.TrimSpace(c.Tab) != "" && c.AllTabs {
+		return usage("--tab and --all-tabs cannot be used together")
+	}
 
 	svc, err := requireDocsService(ctx, flags)
 	if err != nil {
 		return err
 	}
 
-	doc, err := svc.Documents.Get(id).Context(ctx).Do()
+	getCall := svc.Documents.Get(id).Context(ctx)
+	if strings.TrimSpace(c.Tab) != "" || c.AllTabs {
+		getCall = getCall.IncludeTabsContent(true)
+	}
+	doc, err := getCall.Do()
 	if err != nil {
 		if isDocsNotFound(err) {
 			return fmt.Errorf("doc not found or not a Google Doc (id=%s)", id)
@@ -95,9 +105,46 @@ func (c *DocsRawCmd) Run(ctx context.Context, flags *RootFlags) error {
 		return err
 	}
 
+	if strings.TrimSpace(c.Tab) != "" {
+		tab, tabErr := findTab(flattenTabs(doc.Tabs), c.Tab)
+		if tabErr != nil {
+			return tabErr
+		}
+		doc, err = projectRawDocumentTab(doc, tab)
+		if err != nil {
+			return err
+		}
+	}
+
 	return writeRawJSON(ctx, doc, c.Pretty)
 }
 
+func projectRawDocumentTab(doc *docs.Document, tab *docs.Tab) (*docs.Document, error) {
+	if tab == nil || tab.DocumentTab == nil {
+		return nil, errors.New("selected tab has no document content")
+	}
+
+	content := tab.DocumentTab
+	return &docs.Document{
+		Body:                          content.Body,
+		DocumentId:                    doc.DocumentId,
+		DocumentStyle:                 content.DocumentStyle,
+		Footers:                       content.Footers,
+		Footnotes:                     content.Footnotes,
+		Headers:                       content.Headers,
+		InlineObjects:                 content.InlineObjects,
+		Lists:                         content.Lists,
+		NamedRanges:                   content.NamedRanges,
+		NamedStyles:                   content.NamedStyles,
+		PositionedObjects:             content.PositionedObjects,
+		RevisionId:                    doc.RevisionId,
+		SuggestedDocumentStyleChanges: content.SuggestedDocumentStyleChanges,
+		SuggestedNamedStylesChanges:   content.SuggestedNamedStylesChanges,
+		SuggestionsViewMode:           doc.SuggestionsViewMode,
+		Title:                         doc.Title,
+	}, nil
+}
+
 type DocsExportCmd struct {
 	DocID  string         `arg:"" name:"docId" help:"Doc ID"`
 	Output OutputPathFlag `embed:""`
diff --git a/internal/cmd/docs_raw_test.go b/internal/cmd/docs_raw_test.go
