feat(youtube): add subscription and playlist mutations

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 0.25.1 - Unreleased
 
+### Added
+
+- YouTube: add subscription listing and management plus playlist create, add, remove, and delete commands with least-privilege OAuth, dry-run support, structured output, and destructive-operation confirmation. (#767) — thanks @beezly.
+
 ## 0.25.0 - 2026-06-12
 
 ### Added

README.md

@@ -355,21 +355,41 @@ gog forms raw <formId> --pretty
 
 ### YouTube
 
-Docs: [`gog youtube`](docs/commands/gog-youtube.md),
+Docs: [YouTube workflows](docs/youtube.md),
+[`gog youtube`](docs/commands/gog-youtube.md),
 [`youtube channels`](docs/commands/gog-youtube-channels.md),
 [`youtube videos`](docs/commands/gog-youtube-videos.md),
-[`youtube activities`](docs/commands/gog-youtube-activities.md).
+[`youtube activities`](docs/commands/gog-youtube-activities.md),
+[`youtube subscriptions`](docs/commands/gog-youtube-subscriptions.md),
+[`youtube playlists`](docs/commands/gog-youtube-playlists.md).
 
 ```bash
 gog config set youtube_api_key YOUR_API_KEY
 gog yt channels list --id UC_x5XG1OV2P6uZZ5FSM9Ttw --json
 gog yt videos list --chart mostPopular --region US --max 5
 gog yt activities list --mine -a you@gmail.com
+gog yt subscriptions list --all -a you@gmail.com
+gog yt playlists create --title "Research" -a you@gmail.com
 ```
 
 For API-key reads, enable YouTube Data API v3 on the key's Google Cloud project
 and make sure API-key restrictions allow YouTube Data API calls. Authenticated
-`--mine` reads use OAuth instead.
+`--mine` reads use OAuth instead. Subscription and playlist mutations require
+the narrower `youtube.force-ssl` write scope; authorize it explicitly before
+the first write:
+
+```bash
+gog auth add you@gmail.com --services youtube \
+  --extra-scopes https://www.googleapis.com/auth/youtube.force-ssl \
+  --force-consent
+```
+
+All YouTube mutations support `--dry-run`. Unsubscribe, playlist-item removal,
+and playlist deletion also require confirmation or `--force`. New playlists
+default to private; pass `--privacy unlisted` or `--privacy public` explicitly
+to broaden visibility. The authenticated Google account must already have a
+YouTube channel; initialize it once at youtube.com if the API reports
+`youtubeSignupRequired`.
 
 ### Analytics and Search Console
 

docs/commands.generated.md

@@ -626,10 +626,18 @@ Generated from `gog schema --json`.
       - [`gog youtube (yt) channels (channel) list (ls) [flags]`](commands/gog-youtube-channels-list.md) - List channels by ID or authenticated user
     - [`gog youtube (yt) comments (comment) <command>`](commands/gog-youtube-comments.md) - List comment threads
       - [`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) <command>`](commands/gog-youtube-playlists.md) - Manage playlists
+      - [`gog youtube (yt) playlists (playlist) add --playlist-id=STRING --video-id=STRING [flags]`](commands/gog-youtube-playlists-add.md) - Add a video to a playlist
+      - [`gog youtube (yt) playlists (playlist) create --title=STRING [flags]`](commands/gog-youtube-playlists-create.md) - Create a new playlist
+      - [`gog youtube (yt) playlists (playlist) delete (del) <playlist-id>`](commands/gog-youtube-playlists-delete.md) - Delete a playlist
       - [`gog youtube (yt) playlists (playlist) list (ls) [flags]`](commands/gog-youtube-playlists-list.md) - List playlists by channel or authenticated user
+      - [`gog youtube (yt) playlists (playlist) remove (rm) [flags]`](commands/gog-youtube-playlists-remove.md) - Remove a video from a playlist
     - [`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) subscriptions (subscription) <command>`](commands/gog-youtube-subscriptions.md) - Manage channel subscriptions
+      - [`gog youtube (yt) subscriptions (subscription) list (ls) [flags]`](commands/gog-youtube-subscriptions-list.md) - List subscriptions for authenticated user
+      - [`gog youtube (yt) subscriptions (subscription) subscribe [flags]`](commands/gog-youtube-subscriptions-subscribe.md) - Subscribe to a channel
+      - [`gog youtube (yt) subscriptions (subscription) unsubscribe [flags]`](commands/gog-youtube-subscriptions-unsubscribe.md) - Unsubscribe from a channel
     - [`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

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: 634.
+Generated pages: 642.
 
 ## Top-level Commands
 
@@ -677,10 +677,18 @@ Generated pages: 634.
       - [gog youtube channels list](gog-youtube-channels-list.md) - List channels by ID or authenticated user
     - [gog youtube comments](gog-youtube-comments.md) - List comment threads
       - [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](gog-youtube-playlists.md) - Manage playlists
+      - [gog youtube playlists add](gog-youtube-playlists-add.md) - Add a video to a playlist
+      - [gog youtube playlists create](gog-youtube-playlists-create.md) - Create a new playlist
+      - [gog youtube playlists delete](gog-youtube-playlists-delete.md) - Delete a playlist
       - [gog youtube playlists list](gog-youtube-playlists-list.md) - List playlists by channel or authenticated user
+      - [gog youtube playlists remove](gog-youtube-playlists-remove.md) - Remove a video from a playlist
     - [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 subscriptions](gog-youtube-subscriptions.md) - Manage channel subscriptions
+      - [gog youtube subscriptions list](gog-youtube-subscriptions-list.md) - List subscriptions for authenticated user
+      - [gog youtube subscriptions subscribe](gog-youtube-subscriptions-subscribe.md) - Subscribe to a channel
+      - [gog youtube subscriptions unsubscribe](gog-youtube-subscriptions-unsubscribe.md) - Unsubscribe from a channel
     - [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

docs/commands/gog-youtube-playlists-add.md

@@ -0,0 +1,48 @@
+# `gog youtube playlists add`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Add a video to a playlist
+
+## Usage
+
+```bash
+gog youtube (yt) playlists (playlist) add --playlist-id=STRING --video-id=STRING [flags]
+```
+
+## Parent
+
+- [gog youtube playlists](gog-youtube-playlists.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/youtube/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) |
+| `--playlist-id` | `string` |  | Playlist ID |
+| `--position` | `int64` | -1 | Position in playlist (0-based); appends if not set |
+| `--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 |
+| `--video-id` | `string` |  | Video ID to add |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog youtube playlists](gog-youtube-playlists.md)
+- [Command index](README.md)

docs/commands/gog-youtube-playlists-create.md

@@ -0,0 +1,48 @@
+# `gog youtube playlists create`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Create a new playlist
+
+## Usage
+
+```bash
+gog youtube (yt) playlists (playlist) create --title=STRING [flags]
+```
+
+## Parent
+
+- [gog youtube playlists](gog-youtube-playlists.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/youtube/photos) |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--description` | `string` |  | Playlist description |
+| `--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) |
+| `--privacy` | `string` | private | Privacy: public, unlisted, private |
+| `--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. |
+| `--title` | `string` |  | Playlist title |
+| `-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 playlists](gog-youtube-playlists.md)
+- [Command index](README.md)

docs/commands/gog-youtube-playlists-delete.md

@@ -0,0 +1,45 @@
+# `gog youtube playlists delete`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Delete a playlist
+
+## Usage
+
+```bash
+gog youtube (yt) playlists (playlist) delete (del) <playlist-id>
+```
+
+## Parent
+
+- [gog youtube playlists](gog-youtube-playlists.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/youtube/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 playlists](gog-youtube-playlists.md)
+- [Command index](README.md)

docs/commands/gog-youtube-playlists-remove.md

@@ -0,0 +1,48 @@
+# `gog youtube playlists remove`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Remove a video from a playlist
+
+## Usage
+
+```bash
+gog youtube (yt) playlists (playlist) remove (rm) [flags]
+```
+
+## Parent
+
+- [gog youtube playlists](gog-youtube-playlists.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/youtube/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) |
+| `--item-id` | `string` |  | Playlist item ID to remove directly |
+| `-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) |
+| `--playlist-id` | `string` |  | Playlist ID (required with --video-id) |
+| `--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 |
+| `--video-id` | `string` |  | Video ID to remove |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog youtube playlists](gog-youtube-playlists.md)
+- [Command index](README.md)

docs/commands/gog-youtube-playlists.md

@@ -2,7 +2,7 @@
 
 > Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
 
-List playlists
+Manage playlists
 
 ## Usage
 
@@ -16,7 +16,11 @@ gog youtube (yt) playlists (playlist) <command>
 
 ## Subcommands
 
+- [gog youtube playlists add](gog-youtube-playlists-add.md) - Add a video to a playlist
+- [gog youtube playlists create](gog-youtube-playlists-create.md) - Create a new playlist
+- [gog youtube playlists delete](gog-youtube-playlists-delete.md) - Delete a playlist
 - [gog youtube playlists list](gog-youtube-playlists-list.md) - List playlists by channel or authenticated user
+- [gog youtube playlists remove](gog-youtube-playlists-remove.md) - Remove a video from a playlist
 
 ## Flags