jdwit/ytstudio-cli

ytstudio

ytstudio 是一个基于 YouTube 官方数据和分析 API 的命令行工具。它旨在规模化地完成 YouTube Studio 网页界面需要逐项点击的操作：批量元数据编辑、批量上传、脚本化分析、评论审核、直播控制和播放列表管理。

本技能教你如何使用它。它与框架无关：每条指令都是一个 Shell 命令。

首先需要了解的两件事

以下两条规则适用于几乎所有命令，并能防止最常见的错误：

1. 请求 JSON 格式。 读取命令默认输出人类可读的表格。传递 -o json（--output json 的别名）以获得可解析的输出。某些命令也支持 -o csv。认证/设置命令（init、login、status）没有 JSON 模式。
2. 大多数写操作默认是试运行。 带有 --execute 的命令（videos update/search-replace/upload、livestreams schedule/update 以及播放列表写入操作）会预览它们将要执行的操作，并且不会进行任何更改，直到你使用完全相同的命令并加上 --execute 再次运行。始终先预览，在结果重要时向用户展示预览，然后加上 --execute 重新运行。

某些写操作会立即执行，因为它们没有 --execute 选项：评论审核/回复（comments publish、comments reject、comments reply）和直播状态转换（livestreams start、livestreams stop）。请将这些操作视为高风险：在运行前确认意图。

将写操作视为代价高昂且不可逆的操作：它们会消耗 API 配额（请参阅配额部分），并在真实、公开的频道上执行操作。

前提条件

安装

ytstudio 位于 PyPI 上，需要 Python 3.12+。建议使用隔离安装：

uv tool install ytstudio-cli      # 推荐
# 或者: pipx install ytstudio-cli
# 或者: pip install --user ytstudio-cli

CLI 安装为 ytstudio；yts 是同一入口点的短别名。使用 ytstudio --version 验证。

一次性 OAuth 设置

用户需要提供自己的 Google OAuth 客户端（在 Google Cloud Console 中创建的“桌面应用”客户端，并已启用 YouTube Data API v3 和 YouTube Analytics API）。使用下载的客户端密钥 JSON 文件：

ytstudio init --client-secrets path/to/client_secret.json
ytstudio login                    # 打开浏览器进行授权
ytstudio status                   # 确认已认证的频道

在无头服务器上，使用 ytstudio login --headless：它会打印一个 URL，你可以在任何浏览器中打开，然后将失败的 127.0.0.1 重定向 URL 粘贴回来。

如果 ytstudio login 失败并显示 access_denied：

• 使用拥有该频道的 Google 帐户登录。
• 如果 OAuth 应用仍处于“测试”状态，请在 Google Cloud Console -> APIs & Services -> OAuth consent screen -> Test users 下将该帐户添加为测试用户。
• 通过“Advanced -> Continue”点击“Google 尚未验证此应用”的警告。
• 批准所有请求的（只读）范围；在报告成功之前不要关闭标签页。

凭证仅以所有者权限保存在 ~/.config/ytstudio-cli/ 下。此步骤每个频道只需执行一次；除非认证确实出现问题，否则不要重新运行。

如果 ytstudio status 报告没有已认证的频道，请停止并让用户完成 OAuth 设置；你无法为他们完成浏览器授权。

多频道（配置文件）

一次安装可以保存多个频道，每个频道对应一个命名的配置文件。除非被覆盖，否则命令作用于活动的配置文件：

ytstudio profile list             # 标记活动的配置文件
ytstudio profile use work         # 切换活动的配置文件
YTSTUDIO_PROFILE=work ytstudio videos list   # 为单个命令覆盖（用于脚本编写）

在编写脚本时，使用 YTSTUDIO_PROFILE=<name> 环境变量覆盖，这样就不会因依赖全局状态而错误地修改频道内容。

命令组

以下是操作每个区域所需的最少命令。要了解任何命令的完整参数，请按需阅读 references/reference.md，而不是猜测——或者运行 ytstudio <group> <command> --help。

videos - 核心用例

ytstudio videos list -n 100 -o json          # 最近的视频，可解析输出
ytstudio videos list --scheduled             # 仅未发布的视频
ytstudio videos show <video-id> -o json      # 单个视频的完整元数据
ytstudio videos categories                   # 上传时可分配的类别id

# 单个视频编辑（试运行，然后 --execute）
ytstudio videos update <video-id> --title "新标题"
ytstudio videos update <video-id> --tags one,two,three --execute

# 批量搜索替换频道内容（试运行，然后 --execute）
ytstudio videos search-replace -s "2024" -r "2025" -f title
ytstudio videos search-replace -s 'season \d' -r 'season X' -f title --regex --execute

search-replace 需要 -s/--search、-r/--replace 和 -f/--field（title 或 description）；--limit 限制其作用的最大匹配数（默认 10）。先预览试运行结果，确认匹配集是用户想要的，然后添加 --execute。

videos upload - 从 YAML sidecar 文件批量上传

ytstudio videos upload <path> 将每个视频文件与其同名的兄弟 YAML sidecar 文件配对，验证所有内容，然后上传。默认试运行。sidecar 文件的模式（title、description、privacy、tags、category_id（必填）、语言、made_for_kids、可选的 publish_at）请参见 assets/upload-sidecar.example.yaml。

ytstudio videos upload ./outbox               # 验证 + 预览
ytstudio videos upload ./outbox --execute --max 3   # 上传，限制配额

上传是可恢复的：每次成功后，sidecar 文件都会被更新，添加 video_id 和 uploaded_at 字段，因此重新运行只会重试缺少 video_id 的 sidecar 文件。使用 --max 限制单次运行，因为上传消耗大量配额（每个约 1600 单位）。

analytics - 报告（只读）

ytstudio analytics overview -d 28 -o json     # 频道概览，最近28天
ytstudio analytics video <video-id> -o json   # 单个视频的分析数据
ytstudio analytics metrics                     # 可发现的指标名称
ytstudio analytics dimensions                  # 可发现的维度名称

# 针对 Analytics API 的 reports.query 端点的自定义查询：
ytstudio analytics query -m views,likes -d day --days 7 -o json
ytstudio analytics query -m views -d country --sort -views -n 10 -o json
ytstudio analytics query -m views -d insightTrafficSourceType -f video==<id> -o json

analytics query 需要 -m/--metrics；-d/--dimensions、-f/--filter（key==value，可重复）、--sort（前缀 - 表示降序）、-n/--limit 和日期范围（--days 或 -s/-e 开始/结束）是可选的。如果不确定存在哪些指标或维度，请先使用 analytics metrics / analytics dimensions 列出它们，而不是猜测名称。

对于 -d month（以及 -d week），CLI 会将 -s/-e 向下调整到 YouTube Analytics API 所需的边界（每月的第一天），因此 --days 和任意日期都可以正常工作。范围是两端包含的，因此结束月份是您想要数据的最后一个月，而不是下一个月。

# 12 个月，2025 年 6 月到 2026 年 5 月：
ytstudio analytics query -m views -d month -s 2025-06-01 -e 2026-05-01

comments - 审核

ytstudio comments list --status held -o json          # 审核队列
ytstudio comments list -v <video-id> -n 50 -o json
ytstudio comments publish <comment-id> [<comment-id> ...]   # 批准待审核评论；立即执行
ytstudio comments reject <comment-id> --ban                 # 拒绝（+ 可选禁言）；立即执行
ytstudio comments reply <comment-id> -t "谢谢！"           # 立即执行

publish/reject 接受一个或多个评论 ID 并立即执行（没有 --execute 试运行）。reply 也会立即发布。首先确认确切的评论 ID/文本。reject 上的 --ban 也会禁言评论作者——仅在用户明确要求禁言时使用。

livestreams - 直播生命周期

ytstudio livestreams list -s upcoming -o json
ytstudio livestreams show <broadcast-id> --ingest -o json   # 推流地址；密钥已隐藏
ytstudio livestreams schedule -t "标题" --scheduled-start 2026-07-01T19:00:00+02:00 --execute
ytstudio livestreams start <broadcast-id> --to testing      # 立即执行；或 --to live
ytstudio livestreams stop <broadcast-id>                    # 立即执行
ytstudio livestreams update <broadcast-id> --privacy unlisted --execute

schedule/update 在添加 --execute 之前是试运行，但 start/stop 会立即执行。livestreams show --show-key 会显示推流密钥——请将任何此类输出视为机密，切勿将其回显到日志或聊天中。start --to live 会向观众发布；除非用户想要立即开播，否则请优先使用 --to testing。

playlists - 批量操作

ytstudio playlists list -o json
ytstudio playlists items <playlist-id> -o json
ytstudio playlists create -t "标题" --privacy unlisted --execute
ytstudio playlists add <playlist-id> --from-search "主题" -n 20 --execute   # 搜索每次调用消耗 100 单位
ytstudio playlists add <playlist-id> -v <video-id> -v <video-id> --execute
ytstudio playlists reorder <playlist-id> --by views --order desc --execute
ytstudio playlists remove <playlist-id> -v <video-id> --execute
ytstudio playlists delete <playlist-id> --execute -y         # -y 跳过提示

所有播放列表写入操作在添加 --execute 之前都是试运行。delete 也会提示确认，除非传递了 -y/--yes；仅当以非交互方式运行且用户已确认删除时才添加 -y。

配额意识

YouTube Data API 的默认预算为每个项目每天 10,000 单位，于太平洋时间午夜重置。大致成本如下：

操作	成本
读取（列出/显示视频、评论、播放列表；分析）	~1 单位
写入（更新视频、审核评论、播放列表插入/重新排序、安排直播）	~50 单位
搜索（playlists add --from-search）	~100 单位/次调用
上传（videos upload）	~1600 单位

在开始大规模批量操作（例如，对数百个视频进行 search-replace，或进行多次上传）之前，请估算成本，如果可能耗尽每日配额，请警告用户。quotaExceeded 响应（HTTP 403）意味着预算已用完，直到下次重置；长时间运行的作业（videos upload）会干净地停止，并报告成功数量，以便稍后恢复。

推荐给代理的工作流程

1. 使用 ytstudio status（如果可能涉及多个频道，则使用 profile list）确认设置。编写脚本时，使用 YTSTUDIO_PROFILE= 选择频道。
2. 使用带 -o json 的读取命令收集状态并解析结果。
3. 对于任何更改，先运行不带 --execute 的命令，检查预览，并在更改具有重大影响或是批量操作时向用户展示。
4. 使用完全相同的命令并添加 --execute 来应用更改。
5. 注意批量操作和上传操作的配额。

当某个标志或行为不明确时，请查阅 references/reference.md 或 --help，而不是自行假设。