feat(youtube): add search command

BRO3886 · web-flow · commit b77da7ff559f · 2026-05-30T22:03:03.000+01:00
Adds `gog youtube search list` / `gog yt search ls` for YouTube Data API search across videos, channels, and playlists, with table/JSON output and generated command docs.

Maintainer fixups: rebased onto current main, reused the shared YouTube read-service selector so `--account`/`--account auto` use OAuth while public reads can still use API keys, added `videoCount` ordering support per YouTube `search.list`, added focused unit coverage, and updated the changelog.

Proof:
- `go test ./internal/cmd -run 'TestYouTube'`
- `make ci`
- Autoreview clean: no accepted/actionable findings after fixups
- Live OAuth proof with `clawdbot@gmail.com`: `GOG_YOUTUBE_API_KEY=definitely-invalid ./bin/gog --account clawdbot@gmail.com --json youtube search list "openclaw" --type video --order relevance --max 2` returned 2 items, proving account OAuth won over the invalid API key
- GitHub CI green: ci/test, ci/worker, ci/windows, ci/darwin-cgo-build, docker/image

Co-authored-by: Siddhartha Varma &lt;39856034+BRO3886@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,7 @@
 - Docs: add `docs cell-update` for non-destructive table-cell content replacement by table, row, and column. (#646)
 - Gmail: pause watch push Gmail API fetches per account while a 429 Retry-After circuit is open. (#643)
 - YouTube: let `videos list` and `comments list` use OAuth when `--account` is supplied, preserving the API-key fallback for unauthenticated public reads. (#664)
+- YouTube: add `youtube search list` / `yt search ls` for YouTube Data API search across videos, channels, and playlists. (#650, #651) — thanks @BRO3886.
 - Docs: update the bundled `gog` agent skill to preserve broad user OAuth scopes during reauth and rely on command guards for scoped execution.
 
 ## 0.19.0 - 2026-05-22
diff --git a/docs/commands.generated.md b/docs/commands.generated.md
@@ -561,7 +561,7 @@ Generated from `gog schema --json`.
   - [`gog upload (up,put) <localPath> [flags]`](commands/gog-upload.md) - Upload a file to Drive (alias for 'drive upload')
   - [`gog version [flags]`](commands/gog-version.md) - Print version
   - [`gog whoami (who-am-i) [flags]`](commands/gog-whoami.md) - Show your profile (alias for 'people me')
-  - [`gog youtube (yt) <command> [flags]`](commands/gog-youtube.md) - YouTube Data API (activities, videos, playlists, comments, channels)
+  - [`gog youtube (yt) <command> [flags]`](commands/gog-youtube.md) - YouTube Data API (search, activities, videos, playlists, comments, channels)
     - [`gog youtube (yt) activities (activity) <command>`](commands/gog-youtube-activities.md) - List channel activities
       - [`gog youtube (yt) activities (activity) list (ls) [flags]`](commands/gog-youtube-activities-list.md) - List activities for a channel (or authenticated user)
     - [`gog youtube (yt) channels (channel) <command>`](commands/gog-youtube-channels.md) - List channels
@@ -570,6 +570,8 @@ Generated from `gog schema --json`.
       - [`gog youtube (yt) comments (comment) list (ls) [flags]`](commands/gog-youtube-comments-list.md) - List comment threads for a video or channel
     - [`gog youtube (yt) playlists (playlist) <command>`](commands/gog-youtube-playlists.md) - List playlists
       - [`gog youtube (yt) playlists (playlist) list (ls) [flags]`](commands/gog-youtube-playlists-list.md) - List playlists by channel or authenticated user
+    - [`gog youtube (yt) search (find) <command>`](commands/gog-youtube-search.md) - Search YouTube for videos, channels, or playlists
+      - [`gog youtube (yt) search (find) list (ls) <query> [flags]`](commands/gog-youtube-search-list.md) - Search for videos, channels, or playlists
     - [`gog youtube (yt) videos (video) <command>`](commands/gog-youtube-videos.md) - List or get videos
       - [`gog youtube (yt) videos (video) list (ls) [flags]`](commands/gog-youtube-videos-list.md) - List videos by ID or chart
   - [`gog zoom <command> [flags]`](commands/gog-zoom.md) - Zoom
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: 574.
+Generated pages: 576.
 
 ## Top-level Commands
 
@@ -48,7 +48,7 @@ Generated pages: 574.
 - [gog upload](gog-upload.md) - Upload a file to Drive (alias for 'drive upload')
 - [gog version](gog-version.md) - Print version
 - [gog whoami](gog-whoami.md) - Show your profile (alias for 'people me')
-- [gog youtube](gog-youtube.md) - YouTube Data API (activities, videos, playlists, comments, channels)
+- [gog youtube](gog-youtube.md) - YouTube Data API (search, activities, videos, playlists, comments, channels)
 - [gog zoom](gog-zoom.md) - Zoom
 
 ## All Commands
@@ -612,7 +612,7 @@ Generated pages: 574.
   - [gog upload](gog-upload.md) - Upload a file to Drive (alias for 'drive upload')
   - [gog version](gog-version.md) - Print version
   - [gog whoami](gog-whoami.md) - Show your profile (alias for 'people me')
-  - [gog youtube](gog-youtube.md) - YouTube Data API (activities, videos, playlists, comments, channels)
+  - [gog youtube](gog-youtube.md) - YouTube Data API (search, activities, videos, playlists, comments, channels)
     - [gog youtube activities](gog-youtube-activities.md) - List channel activities
       - [gog youtube activities list](gog-youtube-activities-list.md) - List activities for a channel (or authenticated user)
     - [gog youtube channels](gog-youtube-channels.md) - List channels
@@ -621,6 +621,8 @@ Generated pages: 574.
       - [gog youtube comments list](gog-youtube-comments-list.md) - List comment threads for a video or channel
     - [gog youtube playlists](gog-youtube-playlists.md) - List playlists
       - [gog youtube playlists list](gog-youtube-playlists-list.md) - List playlists by channel or authenticated user
+    - [gog youtube search](gog-youtube-search.md) - Search YouTube for videos, channels, or playlists
+      - [gog youtube search list](gog-youtube-search-list.md) - Search for videos, channels, or playlists
     - [gog youtube videos](gog-youtube-videos.md) - List or get videos
       - [gog youtube videos list](gog-youtube-videos-list.md) - List videos by ID or chart
   - [gog zoom](gog-zoom.md) - Zoom
diff --git a/docs/commands/gog-youtube-search-list.md b/docs/commands/gog-youtube-search-list.md
@@ -0,0 +1,50 @@
+# `gog youtube search list`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Search for videos, channels, or playlists
+
+## Usage
+
+```bash
+gog youtube (yt) search (find) list (ls) <query> [flags]
+```
+
+## Parent
+
+- [gog youtube search](gog-youtube-search.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/drivelabels/docs/slides/contacts/tasks/people/sheets/forms/sites/appscript/analytics/searchconsole/ads/photos) |
+| `--channel-id` | `string` |  | Restrict results to a specific channel |
+| `--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 |
+| `-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 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 |
+| `--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) |
+| `--max`<br>`--limit` | `int64` | 25 | Max results |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--order` | `string` | relevance | Sort order: relevance, date, rating, title, videoCount, viewCount |
+| `--page` | `string` |  | Page token |
+| `-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. |
+| `--type` | `string` | video | Resource type: video, channel, playlist (comma-separated) |
+| `-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 youtube search](gog-youtube-search.md)
+- [Command index](README.md)
diff --git a/docs/commands/gog-youtube-search.md b/docs/commands/gog-youtube-search.md
@@ -0,0 +1,49 @@
+# `gog youtube search`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Search YouTube for videos, channels, or playlists
+
+## Usage
+
+```bash
+gog youtube (yt) search (find) <command>
+```
+
+## Parent
+
+- [gog youtube](gog-youtube.md)
+
+## Subcommands
+
+- [gog youtube search list](gog-youtube-search-list.md) - Search for videos, channels, or playlists
+
+## 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/drivelabels/docs/slides/contacts/tasks/people/sheets/forms/sites/appscript/analytics/searchconsole/ads/photos) |
+| `--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 |
+| `-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 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 |
+| `--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) |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `-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 |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog youtube](gog-youtube.md)
+- [Command index](README.md)
diff --git a/docs/commands/gog-youtube.md b/docs/commands/gog-youtube.md
@@ -2,7 +2,7 @@
 
 > Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
 
-YouTube Data API (activities, videos, playlists, comments, channels)
+YouTube Data API (search, activities, videos, playlists, comments, channels)
 
 ## Usage
 
@@ -20,6 +20,7 @@ gog youtube (yt) <command> [flags]
 - [gog youtube channels](gog-youtube-channels.md) - List channels
 - [gog youtube comments](gog-youtube-comments.md) - List comment threads
 - [gog youtube playlists](gog-youtube-playlists.md) - List playlists
+- [gog youtube search](gog-youtube-search.md) - Search YouTube for videos, channels, or playlists
 - [gog youtube videos](gog-youtube-videos.md) - List or get videos
 
 ## Flags
diff --git a/docs/commands/gog.md b/docs/commands/gog.md
@@ -58,7 +58,7 @@ gog <command> [flags]
 - [gog upload](gog-upload.md) - Upload a file to Drive (alias for 'drive upload')
 - [gog version](gog-version.md) - Print version
 - [gog whoami](gog-whoami.md) - Show your profile (alias for 'people me')
-- [gog youtube](gog-youtube.md) - YouTube Data API (activities, videos, playlists, comments, channels)
+- [gog youtube](gog-youtube.md) - YouTube Data API (search, activities, videos, playlists, comments, channels)
 - [gog zoom](gog-zoom.md) - Zoom
 
 ## Flags
diff --git a/internal/cmd/root.go b/internal/cmd/root.go
@@ -91,7 +91,7 @@ type CLI struct {
 	AppScript     AppScriptCmd          `cmd:"" name:"appscript" aliases:"script,apps-script" help:"Google Apps Script"`
 	Analytics     AnalyticsCmd          `cmd:"" aliases:"ga" help:"Google Analytics"`
 	SearchConsole SearchConsoleCmd      `cmd:"" name:"searchconsole" aliases:"gsc,search-console,webmasters" help:"Google Search Console"`
-	YouTube       YouTubeCmd            `cmd:"" name:"youtube" aliases:"yt" help:"YouTube Data API (activities, videos, playlists, comments, channels)"`
+	YouTube       YouTubeCmd            `cmd:"" name:"youtube" aliases:"yt" help:"YouTube Data API (search, activities, videos, playlists, comments, channels)"`
 	Photos        PhotosCmd             `cmd:"" name:"photos" aliases:"photo" help:"Google Photos Library API (app-created media)"`
 	Config        ConfigCmd             `cmd:"" help:"Manage configuration"`
 	ExitCodes     AgentExitCodesCmd     `cmd:"" name:"exit-codes" aliases:"exitcodes" help:"Print stable exit codes (alias for 'agent exit-codes')"`
diff --git a/internal/cmd/youtube.go b/internal/cmd/youtube.go
@@ -21,6 +21,7 @@ type YouTubeCmd struct {
 	Playlists  YouTubePlaylistsCmd  `cmd:"" name:"playlists" aliases:"playlist" help:"List playlists"`
 	Comments   YouTubeCommentsCmd   `cmd:"" name:"comments" aliases:"comment" help:"List comment threads"`
 	Channels   YouTubeChannelsCmd   `cmd:"" name:"channels" aliases:"channel" help:"List channels"`
+	Search     YouTubeSearchCmd     `cmd:"" name:"search" aliases:"find" help:"Search YouTube for videos, channels, or playlists"`
 }
 
 type YouTubeActivitiesCmd struct {
@@ -431,6 +432,99 @@ func (c *YouTubeChannelsListCmd) Run(ctx context.Context, flags *RootFlags) erro
 	return nil
 }
 
+type YouTubeSearchCmd struct {
+	List YouTubeSearchListCmd `cmd:"" name:"list" aliases:"ls" help:"Search for videos, channels, or playlists"`
+}
+
+type YouTubeSearchListCmd struct {
+	Query     string `arg:"" help:"Search query"`
+	Type      string `name:"type" help:"Resource type: video, channel, playlist (comma-separated)" default:"video"`
+	Order     string `name:"order" help:"Sort order: relevance, date, rating, title, videoCount, viewCount" default:"relevance" enum:"relevance,date,rating,title,videoCount,viewCount"`
+	ChannelID string `name:"channel-id" help:"Restrict results to a specific channel"`
+	Max       int64  `name:"max" aliases:"limit" help:"Max results" default:"25"`
+	Page      string `name:"page" help:"Page token"`
+}
+
+func (c *YouTubeSearchListCmd) Run(ctx context.Context, flags *RootFlags) error {
+	u := ui.FromContext(ctx)
+	if err := validateYouTubeMax(c.Max); err != nil {
+		return err
+	}
+	if c.Query == "" {
+		return usage("search query is required")
+	}
+
+	types := splitCSV(c.Type)
+	for _, t := range types {
+		switch t {
+		case "video", "channel", "playlist":
+		default:
+			return usage("--type must be video, channel, or playlist (comma-separated)")
+		}
+	}
+
+	svc, err := getYouTubeReadService(ctx, flags)
+	if err != nil {
+		return err
+	}
+
+	call := svc.Search.List([]string{"snippet"}).
+		Q(c.Query).
+		Type(types...).
+		Order(c.Order).
+		MaxResults(c.Max).
+		PageToken(c.Page)
+	if c.ChannelID != "" {
+		call = call.ChannelId(c.ChannelID)
+	}
+	resp, err := call.Do()
+	if err != nil {
+		return err
+	}
+
+	if outfmt.IsJSON(ctx) {
+		return outfmt.WriteJSON(ctx, os.Stdout, map[string]any{
+			"items":         resp.Items,
+			"nextPageToken": resp.NextPageToken,
+		})
+	}
+	if len(resp.Items) == 0 {
+		u.Err().Println("No results")
+		return nil
+	}
+	w, flush := tableWriter(ctx)
+	defer flush()
+	fmt.Fprintln(w, "KIND\tID\tTITLE\tCHANNEL\tPUBLISHED_AT")
+	for _, item := range resp.Items {
+		id := ""
+		kind := ""
+		if item.Id != nil {
+			switch {
+			case item.Id.VideoId != "":
+				id = item.Id.VideoId
+				kind = "video"
+			case item.Id.ChannelId != "":
+				id = item.Id.ChannelId
+				kind = "channel"
+			case item.Id.PlaylistId != "":
+				id = item.Id.PlaylistId
+				kind = "playlist"
+			}
+		}
+		title := ""
+		ch := ""
+		pubAt := ""
+		if item.Snippet != nil {
+			title = item.Snippet.Title
+			ch = item.Snippet.ChannelTitle
+			pubAt = item.Snippet.PublishedAt
+		}
+		fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%s\n", kind, id, sanitizeTab(title), sanitizeTab(ch), sanitizeTab(pubAt))
+	}
+	printNextPageHint(u, resp.NextPageToken)
+	return nil
+}
+
 func validateYouTubeMax(limit int64) error {
 	if limit < 1 || limit > 50 {
 		return usage("--max must be between 1 and 50")
diff --git a/internal/cmd/youtube_test.go b/internal/cmd/youtube_test.go
