# YouTube on boxd

> YouTube is a video-sharing platform with user-generated content, live streaming, and monetization opportunities, widely used for marketing, education, and entertainment.

- Page: https://boxd.sh/integrations/youtube/
- CLI: `run youtube` (51 commands, 14 marked common)
- SDK: `import { youtube } from "@boxd/run"`; every parameter and response type is at `@boxd/run/youtube`
- Triggers: 4
- Connect: `run auth youtube` (Sign in with YouTube), or https://app.boxd.sh/integrations/detail/youtube
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth youtube      # once: prints a link to connect your account
run youtube           # list its commands
run youtube list-channels
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { youtube } from "@boxd/run";

const result = await youtube.listChannels({});
console.log(result);

youtube.on("new-subscription", async (event) => {
  // New YouTube Channel Subscription: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run youtube.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run youtube <command> --help` lists the optional ones. "common" marks what `run youtube` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-video-to-playlist` ·common | `youtube.addVideoToPlaylist()` | `--playlistId` `--videoId` | 1 | Add a video to a playlist by inserting a playlist item |
| `create-channel-section` | `youtube.createChannelSection()` | `--snippet` | 1 | Create a new channel section for the authenticated user's YouTube channel |
| `create-comment-reply` ·common | `youtube.createCommentReply()` | `--parentId` `--textOriginal` | 0 | Create a reply to an existing YouTube comment |
| `create-playlist` ·common | `youtube.createPlaylist()` | `--title` | 2 | Create a new YouTube playlist on the authenticated user's channel |
| `delete-channel-section` | `youtube.deleteChannelSection()` | `--id` | 1 | Delete a YouTube channel section |
| `delete-comment` | `youtube.deleteComment()` | `--id` | 0 | Delete a YouTube comment owned by the authenticated user or channel |
| `delete-playlist` | `youtube.deletePlaylist()` | `--confirmDelete` `--id` | 1 | Delete a YouTube playlist owned by the authenticated user/channel |
| `delete-playlist-item` | `youtube.deletePlaylistItem()` | `--id` | 0 | Delete a playlist item (remove a video from a playlist) |
| `delete-video` | `youtube.deleteVideo()` | `--confirmDelete` `--videoId` | 1 | Delete a YouTube video owned by the authenticated user/channel |
| `get-channel-activities` | `youtube.getChannelActivities()` | `--channelId` | 5 | Gets recent activities from a YouTube channel including video uploads, playlist additions, likes, and other channel events |
| `get-channel-id-by-handle` | `youtube.getChannelIdByHandle()` | `--channel-handle` | 0 | Retrieves the YouTube Channel ID for a specific YouTube channel handle |
| `get-channel-statistics` | `youtube.getChannelStatistics()` | — | 5 | Gets detailed statistics for YouTube channels including subscriber counts, view counts, and video counts |
| `get-video-details-batch` | `youtube.getVideoDetailsBatch()` | `--id` | 2 | Retrieves multiple YouTube video resource parts in a single batch call |
| `get-video-rating` | `youtube.getVideoRating()` | `--id` | 1 | Retrieves the ratings that the authorized user gave to a list of specified videos |
| `list-caption-track` ·common | `youtube.listCaptionTrack()` | `--video-id` | 1 | Retrieves a list of caption tracks for a YouTube video |
| `list-channel-sections` | `youtube.listChannelSections()` | `--part` | 5 | Retrieve channel sections from YouTube |
| `list-channel-videos` | `youtube.listChannelVideos()` | — | 5 | Lists videos from a specified YouTube channel |
| `list-channels` ·common | `youtube.listChannels()` | — | 10 | Lists YouTube channels by ID, handle, username, or ownership status, returning detailed channel information including metadata, statistics, and content details |
| `list-comment-threads` ·common ·deprecated | `youtube.listCommentThreads()` | — | 9 | Use list-comment-threads2 instead |
| `list-comment-threads2` | `youtube.listCommentThreads2()` | `--part` | 10 | Retrieve comment threads from YouTube videos or channels matching API request parameters |
| `list-comments` ·common | `youtube.listComments()` | — | 6 | List individual comments from YouTube videos |
| `list-i18n-languages` | `youtube.listI18nLanguages()` | — | 2 | Returns a list of application languages that the YouTube website supports |
| `list-i18n-regions` | `youtube.listI18nRegions()` | — | 2 | Retrieve a list of content regions that the YouTube website supports |
| `list-live-chat-messages` | `youtube.listLiveChatMessages()` | `--liveChatId` | 5 | List live chat messages for a specific chat |
| `list-most-popular-videos` ·deprecated | `youtube.listMostPopularVideos()` | — | 6 | Use update-video instead |
| `list-playlist-images` | `youtube.listPlaylistImages()` | — | 7 | Retrieve playlist images associated with a specific playlist |
| `list-playlist-items` | `youtube.listPlaylistItems()` | `--playlistId` | 6 | List videos in a playlist, with pagination support |
| `list-super-chat-events` | `youtube.listSuperChatEvents()` | — | 4 | Lists Super Chat events for a channel, showing supporter purchases during live streams |
| `list-user-playlists` | `youtube.listUserPlaylists()` | — | 3 | Retrieves playlists owned by the authenticated user, implicitly using mine=True |
| `list-user-subscriptions` | `youtube.listUserSubscriptions()` | — | 3 | Retrieves the authenticated user's YouTube channel subscriptions, allowing specification of response parts and pagination |
| `list-video-abuse-report-reasons` | `youtube.listVideoAbuseReportReasons()` | — | 2 | Retrieve a list of abuse report reasons that can be used to report abusive videos on YouTube |
| `list-video-categories` | `youtube.listVideoCategories()` | — | 4 | List YouTube video categories that can be associated with videos |
| `load-captions` | `youtube.loadCaptions()` | `--id` | 1 | Downloads a specific YouTube caption track, which must be owned by the authenticated user, and returns its content as text |
| `mark-comment-as-spam` | `youtube.markCommentAsSpam()` | `--id` | 0 | Mark one or more YouTube comments as spam |
| `multipart-upload-video` ·common | `youtube.multipartUploadVideo()` | `--categoryId` `--description` `--privacyStatus` `--title` `--videoFile` | 1 | Uploads a video to YouTube using multipart upload in a single request |
| `post-comment` ·common | `youtube.postComment()` | `--channelId` `--textOriginal` `--videoId` | 0 | Post a new top-level comment on a YouTube video |
| `rate-video` | `youtube.rateVideo()` | `--id` `--rating` | 0 | Add a like or dislike rating to a YouTube video, or remove an existing rating |
| `report-video-abuse` | `youtube.reportVideoAbuse()` | `--reasonId` `--videoId` | 3 | Report a YouTube video for containing abusive content |
| `search-you-tube` | `youtube.searchYouTube()` | `--q` | 9 | Searches YouTube for videos, channels, or playlists using a query term, returning the raw API response |
| `set-comment-moderation-status` ·common | `youtube.setCommentModerationStatus()` | `--id` `--moderationStatus` | 1 | Set the moderation status of one or more YouTube comments |
| `subscribe-channel` | `youtube.subscribeChannel()` | `--channelId` | 0 | Subscribes the authenticated user to a specified YouTube channel, identified by its unique `channelId` which must be valid and existing |
| `unsubscribe-channel` | `youtube.unsubscribeChannel()` | `--subscriptionId` | 0 | Unsubscribe the authenticated user from a YouTube channel by deleting a subscription |
| `update-caption` | `youtube.updateCaption()` | `--id` `--snippet` | 0 | Updates a YouTube caption track's metadata such as name, language, or draft status |
| `update-channel` | `youtube.updateChannel()` | `--id` | 5 | Updates a channel's metadata including branding settings and localizations |
| `update-channel-section` | `youtube.updateChannelSection()` | `--id` | 2 | Update an existing YouTube channel section by ID |
| `update-comment` ·common | `youtube.updateComment()` | `--id` `--textOriginal` | 0 | Modify the text of an existing YouTube comment |
| `update-playlist` ·common | `youtube.updatePlaylist()` | `--id` `--snippet` | 3 | Modify an existing YouTube playlist's metadata (title, description, privacy status) |
| `update-playlist-item` | `youtube.updatePlaylistItem()` | `--id` `--snippet` | 4 | Modify a playlist item's properties such as position or note |
| `update-thumbnail` ·common | `youtube.updateThumbnail()` | `--thumbnailUrl` `--videoId` | 0 | Sets the custom thumbnail for a YouTube video using an image from a URL |
| `update-video` | `youtube.updateVideo()` | `--video-id` | 6 | Updates metadata for a YouTube video identified by videoId, which must exist; an empty list for tags removes all existing tags |
| `upload-video` ·common | `youtube.uploadVideo()` | `--categoryId` `--description` `--privacyStatus` `--tags` `--title` `--videoFilePath` | 0 | Uploads a video file to a YouTube channel; the video file must be in a YouTube-supported format |

## Triggers

`youtube.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"new-activity"` | New YouTube Activity | `channel_id` | Triggers when a new activity is detected on a YouTube channel |
| `"new-playlist-item"` | New Item in YouTube Playlist | `playlist_id` | Triggers when a new item is added to a YouTube playlist |
| `"new-playlist"` | New Playlist in YouTube Channel | `channel_id` | Triggers when a new playlist is added to a YouTube channel |
| `"new-subscription"` | New YouTube Channel Subscription | — | Triggers when a new channel is subscribed |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.