ytstudio-cli

ytstudio

ytstudio は、公式のYouTube Data APIおよびAnalytics APIを利用するコマンドラインツールです。YouTube StudioのWeb UIで一つずつクリックする必要がある作業（バルクメタデータ編集、バッチアップロード、スクリプト化された分析、コメントモデレーション、ライブ配信制御、プレイリスト操作）を大規模に行うために存在します。

このスキルは、ytstudioの操作方法を学ぶためのものです。特定のエージェントに依存せず、すべての指示はシェルコマンドとして提供されます。

最初に理解すべき2つのこと

以下の2つのルールは、ほぼすべてのコマンドに適用され、最もよくあるミスを防ぎます。

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 -> APIとサービス -> OAuth同意画面 -> テストユーザー でそのアカウントを追加してください。
• 「Google がこのアプリを確認していません」という警告は、詳細 -> Continue をクリックして進んでください。
• 要求されたすべての（読み取り専用）スコープを承認し、成功と表示されるまでタブを閉じないでください。

認証情報は ~/.config/ytstudio-cli/ に所有者のみがアクセスできる状態で保存されます。この手順はチャンネルごとに1回限りです。実際に認証が壊れていない限り、再実行しないでください。

ytstudio status が認証されたチャンネルを報告しない場合、ユーザーにOAuth設定の完了を依頼してください。ブラウザでの同意操作を代わりに行うことはできません。

複数チャンネル（プロファイル）

1つのインストールで複数のチャンネルを保持でき、それぞれに名前付きプロファイルを設定できます。コマンドは、上書きされない限りアクティブなプロファイルに対して動作します。

ytstudio profile list             # アクティブなプロファイルがマークされる
ytstudio profile use work         # アクティブなプロファイルを切り替え
YTSTUDIO_PROFILE=work ytstudio videos list   # 1つのコマンドで上書き（スクリプト用）

スクリプトを作成する際は YTSTUDIO_PROFILE=<name> 環境変数による上書きを使用し、グローバルな状態に依存して誤ったチャンネルを変更しないようにしてください。

コマンドグループ

以下は各領域を操作するための最小限の情報です。任意のコマンドの完全なフラグ一覧については、ytstudio <group> <command> --help を実行するか、必要に応じて references/reference.md を参照してください。推測はしないでください。

videos - 主要なユースケース

ytstudio videos list -n 100 -o json          # 最近のアップロード、解析可能
nytstudio videos list --scheduled             # 将来公開予定のもののみ
nytstudio videos show <video-id> -o json      # 1つの動画の全メタデータ
nytstudio 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サイドカーによるバッチアップロード

ytstudio videos upload <path> は、各動画ファイルと同じベース名のYAMLサイドカーファイルをペアにし、すべてを検証してアップロードします。デフォルトでドライランです。サイドカーのスキーマ（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   # アップロード、クォータ制限のため上限付き

アップロードは再開可能です。各成功後にサイドカーに video_id と uploaded_at が書き込まれるため、再実行すると video_id がないサイドカーのみが再試行されます。アップロードはクォータを大量に消費するため（1回あたり約1600ユニット）、--max を使用して実行を制限してください。

analytics - レポート（読み取り専用）

ytstudio analytics overview -d 28 -o json     # チャンネル概要、過去28日間
nytstudio analytics video <video-id> -o json   # 動画ごとの分析
nytstudio analytics metrics                     # 利用可能なメトリクス名を表示
nytstudio 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はYouTube Analytics APIが要求する境界（月初）に -s/-e を切り詰めるため、--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                 # 拒否（＋オプションでBAN）; 即時実行
ytstudio comments reply <comment-id> -t "ありがとうございます！"           # 即時実行

publish/reject は1つ以上のコメントIDを受け取り、即座に実行されます（--execute によるドライランなし）。reply も即座に投稿されます。コメントIDとテキストを事前に確認してください。reject の --ban は投稿者をBANします。ユーザーが明示的にBANを要求した場合のみ使用してください。

livestreams - 放送ライフサイクル

ytstudio livestreams list -s upcoming -o json
ytstudio livestreams show <broadcast-id> --ingest -o json   # 取り込みURL; キーは伏せ字
ytstudio livestreams schedule -t "タイトル" --scheduled-start 2026-07-01T19:00:00+09: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   # 検索は1回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のデフォルトの予算は、プロジェクトあたり1日10,000ユニットで、太平洋時間の午前0時にリセットされます。おおよそのコストは以下の通りです。

操作	コスト
読み取り（動画一覧/表示、コメント、プレイリスト、分析）	約1ユニット
書き込み（動画更新、コメントモデレーション、プレイリスト挿入/並び替え、放送予約）	約50ユニット
検索（playlists add --from-search）	1回あたり約100ユニット
アップロード（videos upload）	約1600ユニット

大規模な一括実行（例：数百の動画に対する search-replace、複数のアップロード）を開始する前に、コストを見積もり、1日のクォータを超過する可能性がある場合はユーザーに警告してください。quotaExceeded 応答（HTTP 403）は、予算が次のリセットまで消費されたことを意味します。長時間のジョブ（videos upload）は正常に停止し、成功した数を報告するため、後で再開できます。

エージェント向け推奨ワークフロー

1. ytstudio status（および複数チャンネルの場合は profile list）で設定を一度確認します。スクリプトを作成する場合は YTSTUDIO_PROFILE= でチャンネルを選択します。
2. 読み取りコマンドを -o json 付きで実行して状態を収集し、結果を解析します。
3. 変更を行う場合は、最初に --execute なしでコマンドを実行し、プレビューを確認します。変更が重要または一括操作の場合は、その結果をユーザーに提示します。
4. 同一のコマンドを --execute 付きで再実行して適用します。
5. 一括操作やアップロードの際はクォータに注意してください。

フラグや動作が不明な場合は、推測せずに references/reference.md または --help を参照してください。