jdwit/ytstudio-cli

ytstudio

ytstudio ist ein Kommandozeilenwerkzeug über die offiziellen YouTube Data und Analytics APIs. Es dient dazu, das in großem Umfang zu erledigen, wofür man in der Weboberfläche von YouTube Studio jeden Eintrag einzeln durchklicken muss: Bulk-Metadaten-Bearbeitungen, Batch-Uploads, skriptgesteuerte Analysen, Kommentarmoderation, Live-Übertragungssteuerung und Playlist-Operationen.

Diese Skill vermittelt die Bedienung. Sie ist nutzerunabhängig: Jede Anweisung ist ein Shell-Befehl.

Zwei Dinge, die man zuerst wissen sollte

Diese beiden Regeln gelten für fast jeden Befehl und verhindern die häufigsten Fehler:

1. Nach JSON fragen. Lese-Befehle geben standardmäßig eine menschenlesbare Tabelle aus. Verwende -o json (Alias für --output json), um eine parsebare Ausgabe zu erhalten. Einige Befehle unterstützen auch -o csv. Die Authentifizierungs-/Einrichtungsbefehle (init, login, status) haben keinen JSON-Modus.
2. Die meisten Änderungen sind standardmäßig Trockenläufe. Befehle mit --execute (videos update/search-replace/upload, livestreams schedule/update und Playlist-Schreibbefehle) zeigen eine Vorschau an, was sie tun würden, und ändern nichts, bis du denselben Befehl mit --execute erneut ausführst. Zeige immer zuerst die Vorschau an, zeige sie dem Benutzer bei wichtigen Änderungen, und führe sie dann mit --execute erneut aus.

Einige Schreibvorgänge werden sofort ausgeführt, da sie kein --execute haben: Kommentarmoderation/-antworten (comments publish, comments reject, comments reply) und Live-Übergänge (livestreams start, livestreams stop). Behandle diese als risikoreich: Bestätige die Absicht, bevor du sie ausführst.

Behandle Schreiboperationen als kostspielig und weitgehend irreversibel: Sie verbrauchen API-Kontingent (siehe Kontingent) und wirken sich auf einen echten, öffentlichen Kanal aus.

Voraussetzungen

Installation

ytstudio ist auf PyPI und benötigt Python 3.12+. Bevorzuge eine isolierte Installation:

uv tool install ytstudio-cli      # empfohlen
# oder: pipx install ytstudio-cli
# oder: pip install --user ytstudio-cli

Das CLI wird als ytstudio installiert; yts ist ein kurzer Alias für denselben Einstiegspunkt. Überprüfe mit ytstudio --version.

Einmalige OAuth-Einrichtung

Der Benutzer bringt seinen eigenen Google OAuth-Client mit (ein „Desktop-App“-Client, der in der Google Cloud Console erstellt wurde, mit aktivierter YouTube Data API v3 und YouTube Analytics API). Mit der heruntergeladenen Client-Secret-JSON:

ytstudio init --client-secrets pfad/zu/client_secret.json
ytstudio login                    # öffnet einen Browser zur Autorisierung
ytstudio status                   # bestätigt den authentifizierten Kanal

Auf einem kopflosen Rechner verwende ytstudio login --headless: Es gibt eine URL aus, die du in einem beliebigen Browser öffnen kannst, und dann fügst du die fehlgeschlagene 127.0.0.1-Weiterleitungs-URL wieder ein.

Wenn ytstudio login mit access_denied fehlschlägt:

• Melde dich mit dem Google-Konto an, das den Kanal besitzt.
• Wenn die OAuth-App noch im „Test“-Modus ist, füge dieses Konto unter Google Cloud Console -> APIs & Dienste -> OAuth-Zustimmungsbildschirm -> Testbenutzer hinzu.
• Klicke dich über „Erweitert“ -> „Weiter“ durch die Warnung „Google hat diese App nicht verifiziert“.
• Genehmige alle angeforderten (schreibgeschützten) Bereiche; schließe den Tab nicht, bis der Erfolg gemeldet wird.

Die Anmeldeinformationen liegen besitzerbezogen unter ~/.config/ytstudio-cli/. Dieser Schritt ist pro Kanal einmalig; führe ihn nicht erneut aus, es sei denn, die Authentifizierung ist tatsächlich defekt.

Wenn ytstudio status keinen authentifizierten Kanal meldet, stoppe und bitte den Benutzer, die OAuth-Einrichtung abzuschließen; du kannst die Browser-Zustimmung nicht für ihn durchführen.

Mehrere Kanäle (Profile)

Eine Installation kann mehrere Kanäle verwalten, jeder als benanntes Profil. Befehle wirken auf das aktive Profil, sofern nicht überschrieben:

ytstudio profile list             # aktives Profil ist markiert
ytstudio profile use work         # aktives Profil wechseln
YTSTUDIO_PROFILE=work ytstudio videos list   # Überschreibung für einen Befehl (Skripting)

Verwende die Umgebungsüberschreibung YTSTUDIO_PROFILE=<name> beim Skripting, damit du nie versehentlich den falschen Kanal änderst, indem du dich auf den globalen Zustand verlässt.

Befehlsgruppen

Im Folgenden findest du das Minimum, um jeden Bereich zu bedienen. Für die vollständige Flag-Oberfläche eines Befehls lies bei Bedarf references/reference.md, anstatt zu raten – oder führe ytstudio <gruppe> <befehl> --help aus.

videos – der Hauptanwendungsfall

ytstudio videos list -n 100 -o json          # aktuelle Uploads, parsebar
ytstudio videos list --scheduled             # nur zukünftige Veröffentlichungen
ytstudio videos show <video-id> -o json      # vollständige Metadaten für ein Video
ytstudio videos categories                   # Kategorie-IDs, die beim Upload zuweisbar sind

# Einzelvideo-Bearbeitung (Trockenlauf, dann --execute)
ytstudio videos update <video-id> --title "Neuer Titel"
ytstudio videos update <video-id> --tags eins,zwei,drei --execute

# Bulk-Suche-und-Ersetze über den gesamten Kanal (Trockenlauf, dann --execute)
ytstudio videos search-replace -s "2024" -r "2025" -f title
ytstudio videos search-replace -s 'Saison \d' -r 'Saison X' -f title --regex --execute

search-replace erfordert -s/--search, -r/--replace und -f/--field (title oder description); --limit begrenzt die Anzahl der Treffer, auf die es wirkt (Standard 10). Zeige die Vorschau des Trockenlaufs, bestätige, dass der Treffersatz dem entspricht, was der Benutzer beabsichtigt hat, und füge dann --execute hinzu.

videos upload – Batch-Upload aus YAML-Begleitdateien

ytstudio videos upload <pfad> paart jede Videodatei mit einer gleichnamigen YAML-Begleitdatei, validiert alles und lädt hoch. Standardmäßig Trockenlauf. Siehe assets/upload-sidecar.example.yaml für das Begleitdatei-Schema (title, description, privacy, tags, category_id (erforderlich), Sprachen, made_for_kids, optional publish_at).

ytstudio videos upload ./ausgang                # validieren + Vorschau
ytstudio videos upload ./ausgang --execute --max 3   # hochladen, begrenzt für Kontingent

Uploads sind fortsetzbar: Nach jedem Erfolg wird die Begleitdatei mit video_id und uploaded_at aktualisiert, sodass eine erneute Ausführung nur Begleitdateien ohne eine video_id wiederholt. Verwende --max, um einen Durchlauf zu begrenzen, da Uploads kontingentintensiv sind (~1600 Einheiten pro Stück).

analytics – Berichte (schreibgeschützt)

ytstudio analytics overview -d 28 -o json     # Kanalübersicht, letzte 28 Tage
ytstudio analytics video <video-id> -o json   # Pro-Video-Analyse
ytstudio analytics metrics                     # abfragbare Metriknamen
ytstudio analytics dimensions                  # abfragbare Dimensionsnamen

# Benutzerdefinierte Abfrage direkt gegen den Analytics-API-reports.query-Endpunkt:
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 benötigt -m/--metrics; -d/--dimensions, -f/--filter (key==value, wiederholbar), --sort (Präfix - für absteigend), -n/--limit und Datumsbereich (--days oder -s/-e Start/Ende) sind optional. Wenn du dir nicht sicher bist, welche Metrik oder Dimension existiert, liste sie zuerst mit analytics metrics / analytics dimensions auf, anstatt Namen zu erraten.

Für -d month (und -d week) passt das CLI -s/-e auf die Grenze an, die die YouTube Analytics API erfordert (erster des Monats), sodass --days und beliebige Daten einfach funktionieren. Der Bereich ist inklusive beider Enden, sodass der Endmonat der letzte gewünschte Monat ist, nicht der Monat danach.

# 12 Monate, Juni 2025 bis Mai 2026:
ytstudio analytics query -m views -d month -s 2025-06-01 -e 2026-05-01

comments – Moderation

ytstudio comments list --status held -o json          # die Moderationswarteschlange
ytstudio comments list -v <video-id> -n 50 -o json
ytstudio comments publish <comment-id> [<comment-id> ...]   # genehmigen; wird sofort ausgeführt
ytstudio comments reject <comment-id> --ban                 # ablehnen (+ optionaler Bann); wird sofort ausgeführt
ytstudio comments reply <comment-id> -t "Danke!"           # wird sofort ausgeführt

publish/reject akzeptieren eine oder mehrere Kommentar-IDs und werden sofort ausgeführt (kein --execute-Trockenlauf). reply wird ebenfalls sofort gepostet. Bestätige zuerst die genauen Kommentar-IDs/-Texte. --ban bei reject bannt auch den Autor – verwende es nur, wenn der Benutzer explizit um einen Bann bittet.

livestreams – Broadcast-Lebenszyklus

ytstudio livestreams list -s upcoming -o json
ytstudio livestreams show <broadcast-id> --ingest -o json   # Ingest-URL; Schlüssel redigiert
ytstudio livestreams schedule -t "Titel" --scheduled-start 2026-07-01T19:00:00+02:00 --execute
ytstudio livestreams start <broadcast-id> --to testing      # wird sofort ausgeführt; oder --to live
ytstudio livestreams stop <broadcast-id>                    # wird sofort ausgeführt
ytstudio livestreams update <broadcast-id> --privacy unlisted --execute

schedule/update sind Trockenläufe bis --execute, aber start/stop werden sofort ausgeführt. livestreams show --show-key gibt den Stream-Schlüssel preis – behandle jede solche Ausgabe als Geheimnis und gib sie niemals in Protokolle oder Chats aus. start --to live veröffentlicht für Zuschauer; bevorzuge --to testing, es sei denn, der Benutzer möchte sofort live gehen.

playlists – Bulk-Operationen

ytstudio playlists list -o json
ytstudio playlists items <playlist-id> -o json
ytstudio playlists create -t "Titel" --privacy unlisted --execute
ytstudio playlists add <playlist-id> --from-search "thema" -n 20 --execute   # Suche kostet 100 Einheiten/Aufruf
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 überspringt die Eingabeaufforderung

Alle Playlist-Schreibvorgänge sind Trockenläufe bis --execute. delete fordert auch zur Bestätigung auf, es sei denn, -y/--yes wird übergeben; füge -y nur hinzu, wenn du nicht interaktiv arbeitest und der Benutzer die Löschung bestätigt hat.

Kontingentbewusstsein

Die YouTube Data API hat ein Standardbudget von 10.000 Einheiten/Tag pro Projekt, das um Mitternacht Pacific zurückgesetzt wird. Ungefähre Kosten:

Operation	Kosten
Lesen (list/show videos, comments, playlists; analytics)	~1 Einheit
Schreiben (update video, moderate comment, playlist insert/reorder, schedule broadcast)	~50 Einheiten
Suche (playlists add --from-search)	~100 Einheiten/Aufruf
Upload (videos upload)	~1600 Einheiten

Bevor du einen großen Bulk-Durchlauf startest (z. B. search-replace über Hunderte von Videos oder mehrere Uploads), schätze die Kosten und warne den Benutzer, wenn das tägliche Kontingent erschöpft werden könnte. Eine quotaExceeded-Antwort (HTTP 403) bedeutet, dass das Budget bis zum nächsten Reset aufgebraucht ist; langlaufende Jobs (videos upload) stoppen sauber und melden, wie viele erfolgreich waren, sodass sie später fortgesetzt werden können.

Empfohlener Arbeitsablauf für einen Agenten

1. Bestätige die Einrichtung einmalig mit ytstudio status (und profile list, wenn mehrere Kanäle involviert sein könnten). Wähle den Kanal beim Skripting mit YTSTUDIO_PROFILE=.
2. Sammle den Zustand mit Lese-Befehlen unter Verwendung von -o json und parsiere das Ergebnis.
3. Führe für jede Änderung den Befehl zuerst ohne --execute aus, überprüfe die Vorschau und zeige sie dem Benutzer an, wenn die Änderung erheblich oder umfangreich ist.
4. Führe denselben Befehl mit --execute erneut aus, um ihn anzuwenden.
5. Beachte das Kontingent für Bulk- und Upload-Operationen.

Wenn ein Flag oder Verhalten unklar ist, konsultiere references/reference.md oder --help, anstatt Annahmen zu treffen.