jdwit/ytstudio-cli

ytstudio

ytstudio 是一個基於官方 YouTube Data 與 Analytics 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 同意畫面 -> 測試使用者中將該帳戶加入。
• 透過「進階」->「繼續」點擊「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 配對，驗證所有內容，然後上傳。預設為乾執行。請參閱 assets/upload-sidecar.example.yaml 了解 sidecar 結構（title、description、privacy、tags、category_id（必要）、語言、made_for_kids、可選的 publish_at）。

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，而非自行假設。