jdwit/ytstudio-cli

ytstudio

ytstudio es una herramienta de línea de comandos sobre las API oficiales de Datos y Analítica de YouTube. Su propósito es realizar a escala lo que la interfaz web de YouTube Studio obliga a hacer clic elemento por elemento: ediciones masivas de metadatos, subidas por lotes, analítica programada, moderación de comentarios, control de transmisiones en vivo y operaciones con listas de reproducción.

Esta habilidad te enseña a usarla. Es independiente del intérprete de comandos: cada instrucción es un comando de shell.

Dos cosas que debes saber primero

Estas dos reglas se aplican a casi todos los comandos y evitan los errores más comunes:

1. Pide JSON. Los comandos de lectura muestran una tabla legible por defecto. Usa -o json (alias de --output json) para obtener una salida procesable. Algunos comandos también aceptan -o csv. Los comandos de autenticación/configuración (init, login, status) no tienen modo JSON.
2. La mayoría de las mutaciones se ejecutan en seco por defecto. Los comandos con --execute (videos update/search-replace/upload, livestreams schedule/update y escrituras en listas de reproducción) muestran una vista previa de lo que harían sin cambiar nada hasta que vuelvas a ejecutar el mismo comando con --execute. Previsualiza siempre primero, muestra la vista previa al usuario cuando sea relevante, y luego vuelve a ejecutar con --execute.

Algunas escrituras se ejecutan inmediatamente porque no tienen --execute: moderación de comentarios/respuestas (comments publish, comments reject, comments reply) y transiciones de transmisiones (livestreams start, livestreams stop). Trátalas como de alto riesgo: confirma la intención antes de ejecutarlas.

Trata las operaciones de escritura como costosas e irreversibles: consumen cuota de API (ver Cuota) y actúan sobre un canal real y público.

Requisitos previos

Instalación

ytstudio está en PyPI y necesita Python 3.12+. Prefiere una instalación aislada:

uv tool install ytstudio-cli      # recomendado
# o: pipx install ytstudio-cli
# o: pip install --user ytstudio-cli

La CLI se instala como ytstudio; yts es un alias corto para el mismo punto de entrada. Verifica con ytstudio --version.

Configuración OAuth única

El usuario debe proporcionar su propio cliente OAuth de Google (un cliente de "Aplicación de escritorio" creado en la Consola de Google Cloud con la API de Datos de YouTube v3 y la API de Analítica de YouTube habilitadas). Con el archivo JSON de secreto del cliente descargado:

ytstudio init --client-secrets ruta/al/client_secret.json
ytstudio login                    # abre un navegador para autorizar
ytstudio status                   # confirma el canal autenticado

En un entorno sin interfaz gráfica, usa ytstudio login --headless: imprime una URL para abrir en cualquier navegador, luego pegas la URL de redirección fallida a 127.0.0.1.

Si ytstudio login falla con access_denied:

• Inicia sesión con la cuenta de Google que posee el canal.
• Si la aplicación OAuth aún está en "Pruebas", agrega esa cuenta en Consola de Google Cloud -> APIs y Servicios -> Pantalla de consentimiento OAuth -> Usuarios de prueba.
• Haz clic en la advertencia "Google no ha verificado esta aplicación" mediante Avanzado -> Continuar.
• Aprueba todos los alcances solicitados (solo lectura); no cierres la pestaña hasta que indique éxito.

Las credenciales se almacenan solo para el propietario en ~/.config/ytstudio-cli/. Este paso se realiza una vez por canal; no lo repitas a menos que la autenticación esté realmente rota.

Si ytstudio status informa que no hay canal autenticado, detente y pídele al usuario que complete la configuración OAuth; no puedes realizar el consentimiento del navegador por él.

Múltiples canales (perfiles)

Una instalación puede contener varios canales, cada uno como un perfil con nombre. Los comandos actúan sobre el perfil activo a menos que se anule:

ytstudio profile list             # el perfil activo está marcado
ytstudio profile use trabajo      # cambia el perfil activo
YTSTUDIO_PROFILE=trabajo ytstudio videos list   # anula para un comando (scripting)

Usa la anulación de entorno YTSTUDIO_PROFILE=<nombre> al hacer scripting para nunca mutar el canal equivocado confiando en el estado global.

Grupos de comandos

A continuación se muestra lo mínimo para operar cada área. Para conocer la superficie completa de banderas de cualquier comando, consulta references/reference.md bajo demanda en lugar de adivinar, o ejecuta ytstudio <grupo> <comando> --help.

videos - el caso de uso principal

ytstudio videos list -n 100 -o json          # subidas recientes, procesable
ytstudio videos list --scheduled             # solo publicaciones con fecha futura
ytstudio videos show <video-id> -o json      # metadatos completos de un video
ytstudio videos categories                   # IDs de categoría asignables al subir

# Edición de un solo video (simulación, luego --execute)
ytstudio videos update <video-id> --title "Nuevo título"
ytstudio videos update <video-id> --tags uno,dos,tres --execute

# Búsqueda y reemplazo masivo en el canal (simulación, luego --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 requiere -s/--search, -r/--replace y -f/--field (title o description); --limit limita cuántas coincidencias procesa (por defecto 10). Previsualiza la simulación, confirma que el conjunto de coincidencias es el que el usuario pretendía, luego agrega --execute.

videos upload - subida por lotes desde archivos YAML acompañantes

ytstudio videos upload <ruta> empareja cada archivo de video con un archivo YAML acompañante del mismo nombre base, valida todo y sube. Por defecto es simulación. Consulta assets/upload-sidecar.example.yaml para el esquema del acompañante (title, description, privacy, tags, category_id (obligatorio), idiomas, made_for_kids, publish_at opcional).

ytstudio videos upload ./outbox               # validar + previsualizar
ytstudio videos upload ./outbox --execute --max 3   # subir, limitado por cuota

Las subidas son reanudables: después de cada éxito, el acompañante se actualiza con video_id y uploaded_at, por lo que volver a ejecutar solo reintenta los acompañantes que carecen de video_id. Usa --max para limitar una ejecución porque las subidas consumen mucha cuota (~1600 unidades cada una).

analytics - informes (solo lectura)

ytstudio analytics overview -d 28 -o json     # resumen del canal, últimos 28 días
ytstudio analytics video <video-id> -o json   # analítica por video
ytstudio analytics metrics                     # nombres de métricas descubribles
ytstudio analytics dimensions                  # nombres de dimensiones descubribles

# Consulta personalizada directa al endpoint reports.query de la API de Analítica:
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 necesita -m/--metrics; -d/--dimensions, -f/--filter (clave==valor, repetible), --sort (prefijo - para descendente), -n/--limit y rango de fechas (--days o -s/-e inicio/fin) son opcionales. Cuando no estés seguro de qué métrica o dimensión existe, listalas primero con analytics metrics / analytics dimensions en lugar de adivinar nombres.

Para -d month (y -d week), la CLI ajusta -s/-e al límite que exige la API de Analítica de YouTube (primer día del mes), por lo que --days y fechas arbitrarias simplemente funcionan. El rango es inclusivo en ambos extremos, por lo que el mes final es el último mes que deseas, no el mes siguiente.

# 12 meses, junio 2025 a mayo 2026:
ytstudio analytics query -m views -d month -s 2025-06-01 -e 2026-05-01

comments - moderación

ytstudio comments list --status held -o json          # la cola de moderación
ytstudio comments list -v <video-id> -n 50 -o json
ytstudio comments publish <comment-id> [<comment-id> ...]   # aprobar retenidos; se ejecuta inmediatamente
ytstudio comments reject <comment-id> --ban                 # rechazar (+ baneo opcional); se ejecuta inmediatamente
ytstudio comments reply <comment-id> -t "¡Gracias!"           # se ejecuta inmediatamente

publish/reject toman uno o más IDs de comentarios y se ejecutan inmediatamente (sin simulación --execute). reply también publica inmediatamente. Confirma primero los IDs/texto exactos de los comentarios. --ban en reject también banea al autor; úsalo solo cuando el usuario lo solicite explícitamente.

livestreams - ciclo de vida de transmisiones

ytstudio livestreams list -s upcoming -o json
ytstudio livestreams show <broadcast-id> --ingest -o json   # URL de ingesta; clave oculta
ytstudio livestreams schedule -t "Título" --scheduled-start 2026-07-01T19:00:00+02:00 --execute
ytstudio livestreams start <broadcast-id> --to testing      # se ejecuta inmediatamente; o --to live
ytstudio livestreams stop <broadcast-id>                    # se ejecuta inmediatamente
ytstudio livestreams update <broadcast-id> --privacy unlisted --execute

schedule/update son simulaciones hasta --execute, pero start/stop se ejecutan inmediatamente. livestreams show --show-key revela la clave de transmisión: trata cualquier salida de este tipo como un secreto y nunca la incluyas en registros o chats. start --to live publica para los espectadores; prefiere --to testing a menos que el usuario quiera salir en vivo de inmediato.

playlists - operaciones masivas

ytstudio playlists list -o json
ytstudio playlists items <playlist-id> -o json
ytstudio playlists create -t "Título" --privacy unlisted --execute
ytstudio playlists add <playlist-id> --from-search "tema" -n 20 --execute   # búsqueda cuesta 100 unidades/llamada
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 omite la confirmación

Todas las escrituras en listas de reproducción son simulaciones hasta --execute. delete también solicita confirmación a menos que se pase -y/--yes; solo agrega -y cuando se ejecute de forma no interactiva y el usuario haya confirmado la eliminación.

Conciencia de la cuota

La API de Datos de YouTube tiene un presupuesto predeterminado de 10 000 unidades/día por proyecto, que se restablece a la medianoche del Pacífico. Costos aproximados:

Operación	Costo
Lectura (listar/mostrar videos, comentarios, listas de reproducción; analítica)	~1 unidad
Escritura (actualizar video, moderar comentario, insertar/reordenar lista de reproducción, programar transmisión)	~50 unidades
Búsqueda (playlists add --from-search)	~100 unidades/llamada
Subida (videos upload)	~1600 unidades

Antes de iniciar una ejecución masiva grande (por ejemplo, search-replace en cientos de videos o varias subidas), estima el costo y advierte al usuario si podría agotar la cuota diaria. Una respuesta quotaExceeded (HTTP 403) significa que el presupuesto se ha agotado hasta el próximo restablecimiento; los trabajos de larga duración (videos upload) se detienen limpiamente e informan cuántos tuvieron éxito, para que puedan reanudarse más tarde.

Flujo de trabajo recomendado para un agente

1. Confirma la configuración una vez con ytstudio status (y profile list si puede haber múltiples canales). Selecciona el canal con YTSTUDIO_PROFILE= al hacer scripting.
2. Recopila el estado con comandos de lectura usando -o json y analiza el resultado.
3. Para cualquier cambio, ejecuta el comando sin --execute primero, inspecciona la vista previa y muéstrasela al usuario cuando el cambio sea relevante o masivo.
4. Vuelve a ejecutar el mismo comando con --execute para aplicarlo.
5. Ten en cuenta la cuota para operaciones masivas y de subida.

Cuando una bandera o comportamiento no esté claro, consulta references/reference.md o --help en lugar de suponer.