youtube-data-cli 0.0.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # youtube-data-cli
 
-YouTube Data API CLI for AI agents (and humans). Search videos, manage playlists, read and post comments, handle subscriptions, and more.
+YouTube Data API CLI for AI agents (and humans). Full coverage of the YouTube Data API v3: search, channels, videos, playlists, comments, subscriptions, captions, thumbnails, and more.
 
 **Works with:** OpenClaw, Claude Code, Cursor, Codex, and any agent that can run shell commands.
 
@@ -25,16 +25,29 @@ Or run directly: `npx youtube-data-cli --help`
 
 Built on the official [YouTube Data API v3](https://developers.google.com/youtube/v3). Uses native `fetch` with no external dependencies beyond `commander`. Every command outputs structured JSON to stdout, ready for agents to parse without extra processing.
 
-Core endpoints covered:
+All 20 YouTube Data API v3 resources covered:
 
 - **[Search](https://developers.google.com/youtube/v3/docs/search/list)** -- search for videos, channels, and playlists
-- **[Channels](https://developers.google.com/youtube/v3/docs/channels/list)** -- get channel details and statistics
-- **[Videos](https://developers.google.com/youtube/v3/docs/videos/list)** -- get video details and statistics
-- **[Playlists](https://developers.google.com/youtube/v3/docs/playlists)** -- list, create, update, and delete playlists
+- **[Channels](https://developers.google.com/youtube/v3/docs/channels)** -- get and update channel details
+- **[Videos](https://developers.google.com/youtube/v3/docs/videos)** -- get, upload, update, delete, rate videos
+- **[Playlists](https://developers.google.com/youtube/v3/docs/playlists)** -- CRUD playlists
 - **[PlaylistItems](https://developers.google.com/youtube/v3/docs/playlistItems)** -- manage videos in playlists
+- **[PlaylistImages](https://developers.google.com/youtube/v3/docs/playlistImages)** -- manage playlist cover images
 - **[CommentThreads](https://developers.google.com/youtube/v3/docs/commentThreads)** -- list and post top-level comments
-- **[Comments](https://developers.google.com/youtube/v3/docs/comments)** -- list, reply, update, and delete comments
+- **[Comments](https://developers.google.com/youtube/v3/docs/comments)** -- CRUD comments, set moderation status
 - **[Subscriptions](https://developers.google.com/youtube/v3/docs/subscriptions)** -- list, subscribe, and unsubscribe
+- **[Activities](https://developers.google.com/youtube/v3/docs/activities)** -- list channel activities
+- **[Captions](https://developers.google.com/youtube/v3/docs/captions)** -- list, upload, download, update, delete captions
+- **[ChannelBanners](https://developers.google.com/youtube/v3/docs/channelBanners)** -- upload channel banner images
+- **[ChannelSections](https://developers.google.com/youtube/v3/docs/channelSections)** -- CRUD channel sections
+- **[I18nLanguages](https://developers.google.com/youtube/v3/docs/i18nLanguages)** -- list supported languages
+- **[I18nRegions](https://developers.google.com/youtube/v3/docs/i18nRegions)** -- list supported regions
+- **[Members](https://developers.google.com/youtube/v3/docs/members)** -- list channel members
+- **[MembershipsLevels](https://developers.google.com/youtube/v3/docs/membershipsLevels)** -- list membership levels
+- **[Thumbnails](https://developers.google.com/youtube/v3/docs/thumbnails)** -- upload video thumbnails
+- **[VideoCategories](https://developers.google.com/youtube/v3/docs/videoCategories)** -- list video categories
+- **[VideoAbuseReportReasons](https://developers.google.com/youtube/v3/docs/videoAbuseReportReasons)** -- list abuse report reasons
+- **[Watermarks](https://developers.google.com/youtube/v3/docs/watermarks)** -- set and unset channel watermarks
 
 ## Setup
 
@@ -44,8 +57,8 @@ This CLI supports two authentication methods:
 
 | Method | Use case | Commands |
 |--------|----------|----------|
-| **API key** | Public data (search, channels, videos, playlists, comments) | Read-only commands |
-| **OAuth 2.0** | Private data + write operations | All commands (required for `*-insert`, `*-update`, `*-delete`, `mine` queries) |
+| **API key** | Public data | `search`, `channels`, `videos`, `playlists`, `playlist-items`, `comment-threads`, `comments`, `channel-sections`, `i18n-languages`, `i18n-regions`, `video-categories`, `video-abuse-report-reasons` |
+| **OAuth 2.0** | Private data + write operations | All `*-insert`, `*-update`, `*-delete` commands, `--mine` queries, `captions`, `members`, `memberships-levels`, `playlist-images`, `thumbnails-set`, `watermarks-*`, `channel-banners-insert` |
 
 ### Option 1: API key only (public data)
 
@@ -63,9 +76,12 @@ For write operations and private data:
 2. Create a project and enable the **YouTube Data API v3**.
 3. Create an **OAuth 2.0 Client ID** (Desktop app type) under "Credentials".
 4. Use the [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/) or your own flow to obtain a refresh token with the required scopes:
-   - `https://www.googleapis.com/auth/youtube` (full access)
-   - or `https://www.googleapis.com/auth/youtube.readonly` (read-only)
-   - or `https://www.googleapis.com/auth/youtube.force-ssl` (for comments)
+   - `https://www.googleapis.com/auth/youtube` -- recommended, covers all operations
+   - `https://www.googleapis.com/auth/youtube.upload` -- add this if using a narrower scope but need video uploads
+
+   Narrower scopes (if you don't need full access):
+   - `https://www.googleapis.com/auth/youtube.readonly` -- read-only access (no write operations)
+   - `https://www.googleapis.com/auth/youtube.force-ssl` -- videos, comments, captions, ratings (read + write)
 
 > **Note:** Service accounts do NOT work with YouTube APIs. You must use OAuth 2.0 with a refresh token.
 
@@ -100,6 +116,8 @@ Credentials are resolved in this order:
 2. `YOUTUBE_API_KEY`, `YOUTUBE_CLIENT_ID`, `YOUTUBE_CLIENT_SECRET`, `YOUTUBE_REFRESH_TOKEN` env vars
 3. `~/.config/youtube-data-cli/credentials.json` (auto-detected)
 
+> **Tip:** If you also use [youtube-analytics-cli](https://github.com/Bin-Huang/youtube-analytics-cli), the environment variable names are the same, so credentials set via env vars are shared automatically between both CLIs.
+
 ## Usage
 
 All commands output pretty-printed JSON by default. Use `--format compact` for compact single-line JSON.
@@ -400,6 +418,303 @@ youtube-data-cli subscriptions-delete --id SUBSCRIPTION_ID
 Options:
 - `--id <id>` -- subscription ID (required)
 
+### channels-update
+
+Update a channel's metadata (OAuth required).
+
+```bash
+youtube-data-cli channels-update --id UCxxxxxxxxxxxxxx --description "New description"
+youtube-data-cli channels-update --id UCxxxxxxxxxxxxxx --country US --keywords "tech,coding"
+```
+
+Options:
+- `--id <id>` -- channel ID (required)
+- `--description <desc>` -- channel description
+- `--keywords <kw>` -- channel keywords
+- `--default-language <lang>` -- default language (ISO 639-1)
+- `--country <code>` -- country (ISO 3166-1 alpha-2)
+- `--made-for-kids <bool>` -- self-declared made for kids (true/false)
+
+### videos-insert
+
+Upload a video (OAuth required).
+
+```bash
+youtube-data-cli videos-insert --file video.mp4 --title "My Video"
+youtube-data-cli videos-insert --file video.mp4 --title "My Video" --description "About this" --tags "tag1,tag2" --privacy public
+```
+
+Options:
+- `--file <path>` -- path to video file (required)
+- `--title <title>` -- video title (required)
+- `--description <desc>` -- video description
+- `--tags <tags>` -- comma-separated tags
+- `--category-id <id>` -- video category ID (default: `22`)
+- `--privacy <status>` -- `public`, `private`, `unlisted` (default: `private`)
+- `--content-type <type>` -- video MIME type (default: `video/mp4`)
+
+### videos-update
+
+Update video metadata (OAuth required).
+
+```bash
+youtube-data-cli videos-update --id VIDEO_ID --title "Updated Title" --category-id 22
+youtube-data-cli videos-update --id VIDEO_ID --title "Title" --category-id 22 --description "Desc" --tags "a,b" --privacy public
+```
+
+Options:
+- `--id <id>` -- video ID (required)
+- `--title <title>` -- video title (required)
+- `--category-id <id>` -- video category ID (required, use `video-categories` to list IDs)
+- `--description <desc>` -- video description
+- `--tags <tags>` -- comma-separated tags
+- `--privacy <status>` -- `public`, `private`, `unlisted`
+- `--default-language <lang>` -- default language (ISO 639-1)
+
+### videos-delete
+
+Delete a video (OAuth required).
+
+```bash
+youtube-data-cli videos-delete --id VIDEO_ID
+```
+
+### videos-rate
+
+Rate a video (OAuth required).
+
+```bash
+youtube-data-cli videos-rate --id VIDEO_ID --rating like
+youtube-data-cli videos-rate --id VIDEO_ID --rating none    # remove rating
+```
+
+Options:
+- `--id <id>` -- video ID (required)
+- `--rating <rating>` -- `like`, `dislike`, or `none` (required)
+
+### videos-get-rating
+
+Get your rating on videos (OAuth required).
+
+```bash
+youtube-data-cli videos-get-rating --id VIDEO_ID
+youtube-data-cli videos-get-rating --id VIDEO_ID1,VIDEO_ID2
+```
+
+### videos-report-abuse
+
+Report a video for abuse (OAuth required).
+
+```bash
+youtube-data-cli videos-report-abuse --video-id VIDEO_ID --reason-id REASON_ID
+```
+
+Options:
+- `--video-id <id>` -- video ID (required)
+- `--reason-id <id>` -- abuse reason ID (required)
+- `--secondary-reason-id <id>` -- secondary reason ID
+- `--comments <text>` -- additional comments
+
+### comments-set-moderation-status
+
+Set moderation status of comments (OAuth required).
+
+```bash
+youtube-data-cli comments-set-moderation-status --id COMMENT_ID --moderation-status published
+youtube-data-cli comments-set-moderation-status --id COMMENT_ID --moderation-status rejected --ban-author
+```
+
+Options:
+- `--id <ids>` -- comment ID(s), comma-separated (required)
+- `--moderation-status <status>` -- `published`, `heldForReview`, `rejected` (required)
+- `--ban-author` -- ban the author from future comments
+
+### activities
+
+List channel activities.
+
+```bash
+youtube-data-cli activities --channel-id UCxxxxxxxxxxxxxx
+youtube-data-cli activities --mine    # your activities (OAuth required)
+```
+
+Options:
+- `--channel-id <id>` -- channel ID
+- `--mine` -- list your activities (OAuth required)
+- `--part <parts>` -- parts to include (default: `snippet,contentDetails`)
+- `--max-results <n>` -- max results 1-50 (default: `25`)
+- `--page-token <token>` -- pagination token
+- `--published-after <datetime>` -- filter after date (RFC 3339)
+- `--published-before <datetime>` -- filter before date (RFC 3339)
+
+### captions
+
+List caption tracks for a video.
+
+```bash
+youtube-data-cli captions --video-id VIDEO_ID
+```
+
+### captions-insert
+
+Upload a caption track (OAuth required).
+
+```bash
+youtube-data-cli captions-insert --video-id VIDEO_ID --file subs.srt --language en --name "English"
+```
+
+Options:
+- `--video-id <id>` -- video ID (required)
+- `--file <path>` -- path to caption file (required)
+- `--language <lang>` -- caption language BCP-47 (required)
+- `--name <name>` -- caption track name (required)
+- `--content-type <type>` -- MIME type (default: `application/octet-stream`)
+- `--is-draft` -- mark as draft
+
+### captions-update
+
+Update a caption track (OAuth required).
+
+```bash
+youtube-data-cli captions-update --id CAPTION_ID --file new-subs.srt
+youtube-data-cli captions-update --id CAPTION_ID --is-draft false
+```
+
+### captions-download
+
+Download a caption track (OAuth required).
+
+```bash
+youtube-data-cli captions-download --id CAPTION_ID
+youtube-data-cli captions-download --id CAPTION_ID --tfmt srt --output subs.srt
+youtube-data-cli captions-download --id CAPTION_ID --tlang fr    # translated
+```
+
+Options:
+- `--id <id>` -- caption track ID (required)
+- `--tfmt <format>` -- format: `sbv`, `scc`, `srt`, `ttml`, `vtt`
+- `--tlang <lang>` -- translation language (BCP-47)
+- `--output <path>` -- save to file (default: stdout)
+
+### captions-delete
+
+Delete a caption track (OAuth required).
+
+```bash
+youtube-data-cli captions-delete --id CAPTION_ID
+```
+
+### channel-banners-insert
+
+Upload a channel banner image (OAuth required). Returns a URL to use with channels-update.
+
+```bash
+youtube-data-cli channel-banners-insert --file banner.jpg
+```
+
+Options:
+- `--file <path>` -- path to image file (required, max 6MB)
+- `--content-type <type>` -- MIME type (default: `image/jpeg`)
+
+### channel-sections / channel-sections-insert / channel-sections-update / channel-sections-delete
+
+Manage channel sections.
+
+```bash
+# List
+youtube-data-cli channel-sections --channel-id UCxxxxxxxxxxxxxx
+youtube-data-cli channel-sections --mine
+
+# Create (OAuth)
+youtube-data-cli channel-sections-insert --type singlePlaylist --title "Featured" --playlist-ids PLxxxxxxxxxxxxxx
+
+# Update (OAuth)
+youtube-data-cli channel-sections-update --id SECTION_ID --type singlePlaylist --title "Updated"
+
+# Delete (OAuth)
+youtube-data-cli channel-sections-delete --id SECTION_ID
+```
+
+### i18n-languages / i18n-regions
+
+List supported languages and regions.
+
+```bash
+youtube-data-cli i18n-languages
+youtube-data-cli i18n-languages --hl en
+youtube-data-cli i18n-regions
+youtube-data-cli i18n-regions --hl en
+```
+
+### members / memberships-levels
+
+List channel members and membership levels (OAuth required).
+
+```bash
+youtube-data-cli members
+youtube-data-cli members --max-results 100
+youtube-data-cli memberships-levels
+```
+
+### playlist-images / playlist-images-insert / playlist-images-update / playlist-images-delete
+
+Manage playlist cover images.
+
+```bash
+# List
+youtube-data-cli playlist-images --parent PLxxxxxxxxxxxxxx
+
+# Upload (OAuth)
+youtube-data-cli playlist-images-insert --playlist-id PLxxxxxxxxxxxxxx --file cover.jpg
+
+# Update (OAuth)
+youtube-data-cli playlist-images-update --id IMAGE_ID --playlist-id PLxxxxxxxxxxxxxx --file new-cover.jpg
+
+# Delete (OAuth)
+youtube-data-cli playlist-images-delete --id IMAGE_ID
+```
+
+### thumbnails-set
+
+Upload a custom thumbnail for a video (OAuth required).
+
+```bash
+youtube-data-cli thumbnails-set --video-id VIDEO_ID --file thumb.jpg
+```
+
+Options:
+- `--video-id <id>` -- video ID (required)
+- `--file <path>` -- path to image file (required)
+- `--content-type <type>` -- MIME type (default: `image/jpeg`)
+
+### video-categories
+
+List video categories.
+
+```bash
+youtube-data-cli video-categories
+youtube-data-cli video-categories --region-code JP --hl ja
+youtube-data-cli video-categories --id 1,2,10
+```
+
+### video-abuse-report-reasons
+
+List video abuse report reasons.
+
+```bash
+youtube-data-cli video-abuse-report-reasons
+youtube-data-cli video-abuse-report-reasons --hl en
+```
+
+### watermarks-set / watermarks-unset
+
+Manage channel watermarks (OAuth required).
+
+```bash
+youtube-data-cli watermarks-set --channel-id UCxxxxxxxxxxxxxx --file watermark.png
+youtube-data-cli watermarks-unset --channel-id UCxxxxxxxxxxxxxx
+```
+
 ## Error output
 
 Errors are written to stderr as JSON with an `error` field and a non-zero exit code:

package/dist/api.js

@@ -1,12 +1,21 @@
+import { readFileSync } from "fs";
 import { getAccessToken } from "./auth.js";
 const DATA_API_BASE = "https://www.googleapis.com/youtube/v3";
-export async function callApi(endpoint, opts) {
+const UPLOAD_API_BASE = "https://www.googleapis.com/upload/youtube/v3";
+function buildSearchParams(params) {
+    const searchParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null && value !== "") {
+            searchParams.set(key, value);
+        }
+    }
+    return searchParams;
+}
+async function getAuthHeaders(opts, method) {
     const params = { ...opts.params };
-    const method = opts.method ?? "GET";
     const headers = {
         "Content-Type": "application/json",
     };
-    // Write operations always require OAuth
     const needsOAuth = opts.requireOAuth || method !== "GET" || !opts.creds.api_key;
     if (needsOAuth) {
         const token = await getAccessToken(opts.creds);
@@ -15,21 +24,94 @@ export async function callApi(endpoint, opts) {
     else {
         params.key = opts.creds.api_key;
     }
-    const searchParams = new URLSearchParams();
-    for (const [key, value] of Object.entries(params)) {
-        if (value !== undefined && value !== null && value !== "") {
-            searchParams.set(key, value);
-        }
-    }
+    return { headers, params };
+}
+export async function callApi(endpoint, opts) {
+    const method = opts.method ?? "GET";
+    const { headers, params } = await getAuthHeaders(opts, method);
+    const searchParams = buildSearchParams(params);
     const url = `${DATA_API_BASE}${endpoint}?${searchParams.toString()}`;
     const fetchOpts = { method, headers };
     if (opts.body && method !== "GET" && method !== "DELETE") {
         fetchOpts.body = JSON.stringify(opts.body);
     }
     const res = await fetch(url, fetchOpts);
-    // DELETE may return 204 No Content
-    if (method === "DELETE" && res.status === 204) {
-        return { deleted: true };
+    // POST with 204 (rate) or DELETE with 204
+    if (res.status === 204) {
+        return { success: true };
+    }
+    if (opts.rawResponse) {
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(text || `HTTP ${res.status}`);
+        }
+        return res;
+    }
+    const json = (await res.json());
+    if (!res.ok || json.error) {
+        throw new Error(json.error?.message ?? `HTTP ${res.status}`);
+    }
+    return json;
+}
+/** Upload a file using multipart upload (metadata + file content) */
+export async function uploadFile(opts) {
+    const token = await getAccessToken(opts.creds);
+    const method = opts.method ?? "POST";
+    const params = { ...opts.params, uploadType: "multipart" };
+    const searchParams = buildSearchParams(params);
+    const url = `${UPLOAD_API_BASE}${opts.endpoint}?${searchParams.toString()}`;
+    const fileContent = readFileSync(opts.filePath);
+    const boundary = "----YouTubeDataCLIBoundary" + Date.now();
+    const metadataPart = opts.body ? JSON.stringify(opts.body) : "{}";
+    const bodyParts = [
+        `--${boundary}\r\n`,
+        `Content-Type: application/json; charset=UTF-8\r\n\r\n`,
+        `${metadataPart}\r\n`,
+        `--${boundary}\r\n`,
+        `Content-Type: ${opts.contentType}\r\n\r\n`,
+    ];
+    const textEncoder = new TextEncoder();
+    const headerBytes = textEncoder.encode(bodyParts.join(""));
+    const footerBytes = textEncoder.encode(`\r\n--${boundary}--`);
+    const bodyBuffer = new Uint8Array(headerBytes.length + fileContent.length + footerBytes.length);
+    bodyBuffer.set(headerBytes, 0);
+    bodyBuffer.set(fileContent, headerBytes.length);
+    bodyBuffer.set(footerBytes, headerBytes.length + fileContent.length);
+    const res = await fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": `multipart/related; boundary=${boundary}`,
+        },
+        body: bodyBuffer,
+    });
+    if (res.status === 204) {
+        return { success: true };
+    }
+    const json = (await res.json());
+    if (!res.ok || json.error) {
+        throw new Error(json.error?.message ?? `HTTP ${res.status}`);
+    }
+    return json;
+}
+/** Upload a file using simple media upload (file content only, no metadata) */
+export async function uploadFileSimple(opts) {
+    const token = await getAccessToken(opts.creds);
+    const method = opts.method ?? "POST";
+    const params = { ...opts.params, uploadType: "media" };
+    const searchParams = buildSearchParams(params);
+    const url = `${UPLOAD_API_BASE}${opts.endpoint}?${searchParams.toString()}`;
+    const fileContent = readFileSync(opts.filePath);
+    const res = await fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": opts.contentType,
+        },
+        body: fileContent,
+    });
+    if (res.status === 204) {
+        return { success: true };
     }
     const json = (await res.json());
     if (!res.ok || json.error) {

package/dist/commands/activities.js

@@ -0,0 +1,42 @@
+import { loadCredentials } from "../auth.js";
+import { callApi } from "../api.js";
+import { output, fatal } from "../utils.js";
+export function registerActivityCommands(program) {
+    program
+        .command("activities")
+        .description("List channel activities")
+        .option("--channel-id <id>", "Channel ID")
+        .option("--mine", "List authenticated user's activities (OAuth required)")
+        .option("--part <parts>", "Parts to include", "snippet,contentDetails")
+        .option("--max-results <n>", "Max results (1-50)", "25")
+        .option("--page-token <token>", "Pagination token")
+        .option("--published-after <datetime>", "Filter after date (RFC 3339)")
+        .option("--published-before <datetime>", "Filter before date (RFC 3339)")
+        .action(async (opts) => {
+        try {
+            const creds = loadCredentials(program.opts().credentials);
+            const params = {
+                part: opts.part,
+                maxResults: opts.maxResults,
+            };
+            const requireOAuth = !!opts.mine || !opts.channelId;
+            if (opts.channelId) {
+                params.channelId = opts.channelId;
+            }
+            else {
+                params.mine = "true";
+            }
+            if (opts.pageToken)
+                params.pageToken = opts.pageToken;
+            if (opts.publishedAfter)
+                params.publishedAfter = opts.publishedAfter;
+            if (opts.publishedBefore)
+                params.publishedBefore = opts.publishedBefore;
+            const data = await callApi("/activities", { creds, params, requireOAuth });
+            output(data, program.opts().format);
+        }
+        catch (err) {
+            fatal(err.message);
+        }
+    });
+}