feat(drive): add read-only reporting commands (#554)

Co-authored-by: Rohan Patnaik <rohan-patnaik@users.noreply.github.com>

Author: steipete

CHANGELOG.md

@@ -8,6 +8,7 @@
 - Raw API dumps: add `docs raw`, `sheets raw`, `slides raw`, `drive raw`, `gmail raw`, `calendar raw`, `people raw`, `contacts raw`, `tasks raw`, and `forms raw` subcommands for lossless Google API JSON output, with `--pretty`, Drive raw redaction defaults, Sheets grid-data warnings, and a raw-output security audit. (#495, #496) — thanks @karbassi.
 - Docs: add `docs format` and plain-text `docs write` formatting flags for fonts, colors, bold/italic/underline/strikethrough, alignment, and line spacing. (#479) — thanks @mmaghsoodnia.
 - Drive: add `--fields` to `drive ls` and `drive get` so callers can pass Drive API field masks for fields beyond the default JSON set. (#495) — thanks @karbassi.
+- Drive: add read-only `drive tree`, `drive du`, and `drive inventory` reports for auditing folder contents and sizes. (#116) — thanks @rohan-patnaik.
 - Sheets: add `sheets table` list/get/create/delete commands for Google Sheets structured tables. (#470) — thanks @Pedrohgv.
 - Agent safety: add baked safety-profile builds for fail-closed agent binaries, with `agent-safe`, `readonly`, and `full` profiles, filtered help/schema output, docs, and build tooling. (#366, #239) — thanks @drewburchfield.
 - Calendar: add `--with-meet` to `calendar update` for adding Google Meet conferencing to existing events. (#538) — thanks @alexisperumal.

README.md

@@ -13,7 +13,7 @@ Fast, script-friendly CLI for Gmail, Calendar, Chat, Classroom, Drive, Docs, Sli
 - **Calendar** - list/create/update/delete events, manage invitations, aliases, subscriptions, team calendars, free/busy/conflicts, propose new times, focus/OOO/working-location events, recurrence, and reminders
 - **Classroom** - manage courses, roster, coursework/materials, submissions, announcements, topics, invitations, guardians, profiles
 - **Chat** - list/find/create spaces, list messages/threads, send messages and DMs, and manage emoji reactions (Workspace-only)
-- **Drive** - list/search/upload/download files, scope search to folders or shared drives, replace uploads in-place, convert uploads (including Markdown to Google Doc), manage permissions/comments, organize folders, and list shared drives
+- **Drive** - list/search/upload/download files, inspect folders with tree/du/inventory reports, scope search to folders or shared drives, replace uploads in-place, convert uploads (including Markdown to Google Doc), manage permissions/comments, organize folders, and list shared drives
 - **Contacts** - search/create/update contacts, including addresses, relations, org/title metadata, custom fields, Workspace directory, and other contacts
 - **Tasks** - manage tasklists and tasks: get/create/add/update/done/undo/delete/clear, plus repeat schedule materialization with RRULE aliases
 - **Sheets** - read/write/update spreadsheets, insert rows/cols, manage tabs, named ranges, and Sheets tables, format/merge/freeze/resize cells, manage conditional formatting and banding, read/write notes, inspect formats, find/replace text, list links, and create/export sheets
@@ -1132,6 +1132,12 @@ gog drive get <fileId>                # Get file metadata
 gog drive url <fileId>                # Print Drive web URL
 gog drive copy <fileId> "Copy Name"
 
+# Read-only reports
+gog drive tree --parent <folderId> --depth 2
+gog drive inventory --parent <folderId> --max 500 --sort modified --order desc
+gog drive du --parent <folderId> --depth 1 --max 50
+gog --json drive inventory --parent <folderId> --max 100 | jq '.items[] | {path,size,modifiedTime}'
+
 # Upload and download
 gog drive upload ./path/to/file --parent <folderId>
 gog drive upload ./path/to/file --replace <fileId>  # Replace file content in-place (preserves shared link)

docs/commands.generated.md

@@ -245,7 +245,9 @@ Generated from `gog schema --json`.
     - [`gog drive (drv) delete (rm,del) <fileId> [flags]`](commands/gog-drive-delete.md) - Move a file to trash (use --permanent to delete forever)
     - [`gog drive (drv) download <fileId> [flags]`](commands/gog-drive-download.md) - Download a file (exports Google Docs formats)
     - [`gog drive (drv) drives [flags]`](commands/gog-drive-drives.md) - List shared drives (Team Drives)
+    - [`gog drive (drv) du [flags]`](commands/gog-drive-du.md) - Summarize Drive folder sizes
     - [`gog drive (drv) get <fileId> [flags]`](commands/gog-drive-get.md) - Get file metadata
+    - [`gog drive (drv) inventory [flags]`](commands/gog-drive-inventory.md) - Export a read-only Drive inventory
     - [`gog drive (drv) ls [flags]`](commands/gog-drive-ls.md) - List files in a folder (default: root)
     - [`gog drive (drv) mkdir <name> [flags]`](commands/gog-drive-mkdir.md) - Create a folder
     - [`gog drive (drv) move <fileId> [flags]`](commands/gog-drive-move.md) - Move a file to a different folder
@@ -254,6 +256,7 @@ Generated from `gog schema --json`.
     - [`gog drive (drv) rename <fileId> <newName>`](commands/gog-drive-rename.md) - Rename a file or folder
     - [`gog drive (drv) search <query> ... [flags]`](commands/gog-drive-search.md) - Full-text search across Drive
     - [`gog drive (drv) share <fileId> [flags]`](commands/gog-drive-share.md) - Share a file or folder
+    - [`gog drive (drv) tree [flags]`](commands/gog-drive-tree.md) - Print a read-only folder tree
     - [`gog drive (drv) unshare <fileId> <permissionId>`](commands/gog-drive-unshare.md) - Remove a permission from a file
     - [`gog drive (drv) upload <localPath> [flags]`](commands/gog-drive-upload.md) - Upload a file
     - [`gog drive (drv) url <fileId> ...`](commands/gog-drive-url.md) - Print web URLs for files

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: 466.
+Generated pages: 469.
 
 ## Top-level Commands
 
@@ -288,7 +288,9 @@ Generated pages: 466.
     - [gog drive delete](gog-drive-delete.md) - Move a file to trash (use --permanent to delete forever)
     - [gog drive download](gog-drive-download.md) - Download a file (exports Google Docs formats)
     - [gog drive drives](gog-drive-drives.md) - List shared drives (Team Drives)
+    - [gog drive du](gog-drive-du.md) - Summarize Drive folder sizes
     - [gog drive get](gog-drive-get.md) - Get file metadata
+    - [gog drive inventory](gog-drive-inventory.md) - Export a read-only Drive inventory
     - [gog drive ls](gog-drive-ls.md) - List files in a folder (default: root)
     - [gog drive mkdir](gog-drive-mkdir.md) - Create a folder
     - [gog drive move](gog-drive-move.md) - Move a file to a different folder
@@ -297,6 +299,7 @@ Generated pages: 466.
     - [gog drive rename](gog-drive-rename.md) - Rename a file or folder
     - [gog drive search](gog-drive-search.md) - Full-text search across Drive
     - [gog drive share](gog-drive-share.md) - Share a file or folder
+    - [gog drive tree](gog-drive-tree.md) - Print a read-only folder tree
     - [gog drive unshare](gog-drive-unshare.md) - Remove a permission from a file
     - [gog drive upload](gog-drive-upload.md) - Upload a file
     - [gog drive url](gog-drive-url.md) - Print web URLs for files

docs/commands/gog-drive-du.md

@@ -0,0 +1,48 @@
+# `gog drive du`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Summarize Drive folder sizes
+
+## Usage
+
+```bash
+gog drive (drv) du [flags]
+```
+
+## Parent
+
+- [gog drive](gog-drive.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 for API commands (gmail/calendar/chat/classroom/drive/docs/slides/contacts/tasks/people/sheets/forms/appscript/ads) |
+| `--all-drives` | `bool` | true | Include shared drives (default: true; use --no-all-drives for My Drive only) |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--depth` | `int` | 1 | Depth for folder totals |
+| `--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-commands` | `string` |  | Comma-separated list of enabled commands; dot paths allowed (restricts CLI) |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--max` | `int` | 50 | Max folders to return (0 = unlimited) |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--order` | `string` | desc | Sort order |
+| `--parent` | `string` |  | Folder ID to start from (default: root) |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
+| `--sort` | `string` | size | Sort by size\|path\|files |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+
+## See Also
+
+- [gog drive](gog-drive.md)
+- [Command index](README.md)

docs/commands/gog-drive-inventory.md

@@ -0,0 +1,48 @@
+# `gog drive inventory`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Export a read-only Drive inventory
+
+## Usage
+
+```bash
+gog drive (drv) inventory [flags]
+```
+
+## Parent
+
+- [gog drive](gog-drive.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 for API commands (gmail/calendar/chat/classroom/drive/docs/slides/contacts/tasks/people/sheets/forms/appscript/ads) |
+| `--all-drives` | `bool` | true | Include shared drives (default: true; use --no-all-drives for My Drive only) |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--depth` | `int` | 0 | Max depth (0 = unlimited) |
+| `--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-commands` | `string` |  | Comma-separated list of enabled commands; dot paths allowed (restricts CLI) |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--max` | `int` | 500 | Max items to return (0 = unlimited) |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--order` | `string` | asc | Sort order |
+| `--parent` | `string` |  | Folder ID to start from (default: root) |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
+| `--sort` | `string` | path | Sort by path\|size\|modified |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+
+## See Also
+
+- [gog drive](gog-drive.md)
+- [Command index](README.md)

docs/commands/gog-drive-tree.md

@@ -0,0 +1,46 @@
+# `gog drive tree`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Print a read-only folder tree
+
+## Usage
+
+```bash
+gog drive (drv) tree [flags]
+```
+
+## Parent
+
+- [gog drive](gog-drive.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 for API commands (gmail/calendar/chat/classroom/drive/docs/slides/contacts/tasks/people/sheets/forms/appscript/ads) |
+| `--all-drives` | `bool` | true | Include shared drives (default: true; use --no-all-drives for My Drive only) |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--depth` | `int` | 2 | Max depth (0 = unlimited) |
+| `--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-commands` | `string` |  | Comma-separated list of enabled commands; dot paths allowed (restricts CLI) |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--max` | `int` | 0 | Max items to return (0 = unlimited) |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--parent` | `string` |  | Folder ID to start from (default: root) |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--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. |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+
+## See Also
+
+- [gog drive](gog-drive.md)
+- [Command index](README.md)

docs/commands/gog-drive.md

@@ -21,7 +21,9 @@ gog drive (drv) <command> [flags]
 - [gog drive delete](gog-drive-delete.md) - Move a file to trash (use --permanent to delete forever)
 - [gog drive download](gog-drive-download.md) - Download a file (exports Google Docs formats)
 - [gog drive drives](gog-drive-drives.md) - List shared drives (Team Drives)
+- [gog drive du](gog-drive-du.md) - Summarize Drive folder sizes
 - [gog drive get](gog-drive-get.md) - Get file metadata
+- [gog drive inventory](gog-drive-inventory.md) - Export a read-only Drive inventory
 - [gog drive ls](gog-drive-ls.md) - List files in a folder (default: root)
 - [gog drive mkdir](gog-drive-mkdir.md) - Create a folder
 - [gog drive move](gog-drive-move.md) - Move a file to a different folder
@@ -30,6 +32,7 @@ gog drive (drv) <command> [flags]
 - [gog drive rename](gog-drive-rename.md) - Rename a file or folder
 - [gog drive search](gog-drive-search.md) - Full-text search across Drive
 - [gog drive share](gog-drive-share.md) - Share a file or folder
+- [gog drive tree](gog-drive-tree.md) - Print a read-only folder tree
 - [gog drive unshare](gog-drive-unshare.md) - Remove a permission from a file
 - [gog drive upload](gog-drive-upload.md) - Upload a file
 - [gog drive url](gog-drive-url.md) - Print web URLs for files

internal/cmd/drive.go

@@ -33,6 +33,8 @@ var (
 )
 
 const (
+	driveRootID            = "root"
+	driveMimeFolder        = "application/vnd.google-apps.folder"
 	driveMimeGoogleDoc     = "application/vnd.google-apps.document"
 	driveMimeGoogleSheet   = "application/vnd.google-apps.spreadsheet"
 	driveMimeGoogleSlides  = "application/vnd.google-apps.presentation"
@@ -70,6 +72,9 @@ const (
 type DriveCmd struct {
 	Ls          DriveLsCmd          `cmd:"" name:"ls" help:"List files in a folder (default: root)"`
 	Search      DriveSearchCmd      `cmd:"" name:"search" help:"Full-text search across Drive"`
+	Tree        DriveTreeCmd        `cmd:"" name:"tree" help:"Print a read-only folder tree"`
+	Du          DriveDuCmd          `cmd:"" name:"du" help:"Summarize Drive folder sizes"`
+	Inventory   DriveInventoryCmd   `cmd:"" name:"inventory" help:"Export a read-only Drive inventory"`
 	Get         DriveGetCmd         `cmd:"" name:"get" help:"Get file metadata"`
 	Download    DriveDownloadCmd    `cmd:"" name:"download" help:"Download a file (exports Google Docs formats)"`
 	Copy        DriveCopyCmd        `cmd:"" name:"copy" help:"Copy a file"`
@@ -945,7 +950,7 @@ func escapeDriveQueryString(s string) string {
 }
 
 func driveType(mimeType string) string {
-	if mimeType == "application/vnd.google-apps.folder" {
+	if mimeType == driveMimeFolder {
 		return "folder"
 	}
 	return strFile