jdwit/ytstudio-cli

ytstudio

ytstudio é uma ferramenta de linha de comando sobre as APIs oficiais do YouTube Data e Analytics. Ela existe para fazer em escala o que a interface web do YouTube Studio faz você clicar item por item: edições em massa de metadados, uploads em lote, análises programadas, moderação de comentários, controle de transmissão ao vivo e operações de playlist.

Esta habilidade ensina você a usá-la. Ela é independente de ambiente: cada instrução é um comando shell.

Duas coisas para saber primeiro

Estas duas regras se aplicam a quase todos os comandos e evitam os erros mais comuns:

1. Peça JSON. Comandos de leitura exibem uma tabela legível por padrão. Use -o json (atalho para --output json) para obter saída parseável. Alguns comandos também suportam -o csv. Os comandos de autenticação/configuração (init, login, status) não possuem modo JSON.
2. A maioria das mutações é dry-run por padrão. Comandos com --execute (videos update/search-replace/upload, livestreams schedule/update e escritas em playlists) pré-visualizam o que fariam e não alteram nada até que você execute novamente o comando exato com --execute. Sempre pré-visualize primeiro, mostre a pré-visualização ao usuário quando for relevante e depois execute novamente com --execute.

Algumas escritas são executadas imediatamente porque não possuem --execute: moderação de comentários/respostas (comments publish, comments reject, comments reply) e transições de transmissão ao vivo (livestreams start, livestreams stop). Trate estas como de alto risco: confirme a intenção antes de executá-las.

Trate operações de escrita como custosas e irreversíveis: elas consomem cota da API (veja Cota) e agem em um canal real e público.

Pré-requisitos

Instalação

ytstudio está no PyPI e requer Python 3.12+. Prefira uma instalação isolada:

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

A CLI é instalada como ytstudio; yts é um alias curto para o mesmo ponto de entrada. Verifique com ytstudio --version.

Configuração única de OAuth

O usuário fornece seu próprio cliente OAuth do Google (um cliente "Aplicativo de desktop" criado no Console do Google Cloud com a YouTube Data API v3 e YouTube Analytics API ativadas). Com o arquivo JSON de segredos do cliente baixado:

ytstudio init --client-secrets caminho/para/client_secret.json
ytstudio login                    # abre um navegador para autorizar
ytstudio status                   # confirma o canal autenticado

Em uma máquina sem interface gráfica, use ytstudio login --headless: ele imprime uma URL para abrir em qualquer navegador, e então você cola de volta a URL de redirecionamento 127.0.0.1 que deu erro.

Se ytstudio login falhar com access_denied:

• Faça login com a conta do Google que possui o canal.
• Se o aplicativo OAuth ainda estiver em "Teste", adicione essa conta no Console do Google Cloud -> APIs & Serviços -> Tela de consentimento OAuth -> Usuários de teste.
• Clique no aviso "O Google não verificou este aplicativo" através de Avançado -> Continuar.
• Aprove todos os escopos (somente leitura) solicitados; não feche a aba até que ela reporte sucesso.

As credenciais ficam, com permissão apenas para o proprietário, em ~/.config/ytstudio-cli/. Esta etapa é única por canal; não a repita a menos que a autenticação esteja realmente quebrada.

Se ytstudio status informar que não há canal autenticado, pare e peça ao usuário para concluir a configuração OAuth; você não pode fazer o consentimento pelo navegador por eles.

Múltiplos canais (perfis)

Uma instalação pode conter vários canais, cada um como um perfil nomeado. Os comandos atuam no perfil ativo a menos que seja especificado:

ytstudio profile list             # o perfil ativo é marcado
ytstudio profile use trabalho     # alterna o perfil ativo
YTSTUDIO_PROFILE=trabalho ytstudio videos list   # substitui para um comando (scripting)

Use a variável de ambiente YTSTUDIO_PROFILE=<nome> ao fazer scripts para nunca alterar o canal errado dependendo do estado global.

Grupos de comandos

Abaixo está o mínimo para operar cada área. Para a lista completa de flags de qualquer comando, consulte references/reference.md sob demanda, em vez de adivinhar

• ou execute ytstudio <grupo> <comando> --help.

videos - o caso de uso principal

ytstudio videos list -n 100 -o json          # uploads recentes, parseável
ytstudio videos list --scheduled             # apenas publicações com data futura
ytstudio videos show <video-id> -o json      # metadados completos de um vídeo
ytstudio videos categories                   # ids de categoria atribuíveis no upload

# Edição de vídeo único (dry-run, depois --execute)
ytstudio videos update <video-id> --title "Novo título"
ytstudio videos update <video-id> --tags um,dois,três --execute

# Substituição em lote por busca em todo o canal (dry-run, depois --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 requer -s/--search, -r/--replace e -f/--field (title ou description); --limit limita quantas correspondências ele age (padrão 10). Pré-visualize o dry-run, confirme que o conjunto de correspondências é o que o usuário pretendia, e então adicione --execute.

videos upload - upload em lote a partir de sidecars YAML

ytstudio videos upload <caminho> emparelha cada arquivo de vídeo com um arquivo sidecar YAML vizinho de mesmo nome base, valida tudo e faz o upload. Dry-run por padrão. Veja assets/upload-sidecar.example.yaml para o esquema do sidecar (title, description, privacy, tags, category_id (obrigatório), idiomas, made_for_kids, opcional publish_at).

ytstudio videos upload ./outbox               # valida + pré-visualiza
ytstudio videos upload ./outbox --execute --max 3   # upload, limitado pela cota

Uploads são retomáveis: após cada sucesso, o sidecar é atualizado com video_id e uploaded_at, então executar novamente apenas retenta sidecars que não possuem video_id. Use --max para limitar uma execução porque uploads consomem muita cota (~1600 unidades cada).

analytics - relatórios (somente leitura)

ytstudio analytics overview -d 28 -o json     # visão geral do canal, últimos 28 dias
ytstudio analytics video <video-id> -o json   # análises por vídeo
ytstudio analytics metrics                     # nomes de métricas disponíveis
ytstudio analytics dimensions                  # nomes de dimensões disponíveis

# Consulta personalizada direta no endpoint reports.query da API Analytics:
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 precisa de -m/--metrics; -d/--dimensions, -f/--filter (chave==valor, repetível), --sort (prefixo - para decrescente), -n/--limit e intervalo de datas (--days ou -s/-e início/fim) são opcionais. Quando estiver em dúvida sobre qual métrica ou dimensão existe, liste-as primeiro com analytics metrics / analytics dimensions em vez de adivinhar nomes.

Para -d month (e -d week), a CLI ajusta -s/-e para o limite que a API Analytics do YouTube requer (primeiro dia do mês), então --days e datas arbitrárias funcionam perfeitamente. O intervalo é inclusivo em ambas as extremidades, então o mês final é o último mês que você deseja, não o mês seguinte.

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

comments - moderação

ytstudio comments list --status held -o json          # a fila de moderação
ytstudio comments list -v <video-id> -n 50 -o json
ytstudio comments publish <comment-id> [<comment-id> ...]   # aprova retidos; executa imediatamente
ytstudio comments reject <comment-id> --ban                 # rejeita (+ ban opcional); executa imediatamente
ytstudio comments reply <comment-id> -t "Obrigado!"           # executa imediatamente

publish/reject recebem um ou mais ids de comentários e executam imediatamente (sem dry-run com --execute). reply também publica imediatamente. Confirme os ids/texto exatos dos comentários primeiro. --ban em reject também bane o autor - use apenas quando o usuário pedir explicitamente para banir.

livestreams - ciclo de vida da transmissão

ytstudio livestreams list -s upcoming -o json
ytstudio livestreams show <broadcast-id> --ingest -o json   # URL de ingestão; chave ocultada
ytstudio livestreams schedule -t "Título" --scheduled-start 2026-07-01T19:00:00+02:00 --execute
ytstudio livestreams start <broadcast-id> --to testing      # executa imediatamente; ou --to live
ytstudio livestreams stop <broadcast-id>                    # executa imediatamente
ytstudio livestreams update <broadcast-id> --privacy unlisted --execute

schedule/update são dry-run até --execute, mas start/stop executam imediatamente. livestreams show --show-key revela a chave de stream - trate qualquer saída como um segredo e nunca a exiba em logs ou chat. start --to live publica para os espectadores; prefira --to testing a menos que o usuário queira ir ao ar imediatamente.

playlists - operações em lote

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 "tópico" -n 20 --execute   # busca custa 100 unidades/chamada
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 pula a confirmação

Todas as escritas em playlists são dry-run até --execute. delete também pede confirmação, a menos que -y/--yes seja passado; adicione -y apenas ao executar de forma não interativa e o usuário já tiver confirmado a exclusão.

Consciência de cota

A API de Dados do YouTube tem um orçamento padrão de 10.000 unidades/dia por projeto, reiniciando à meia-noite do Pacífico. Custos aproximados:

Operação	Custo
Leitura (listar/mostrar vídeos, comentários, playlists; análises)	~1 unidade
Escrita (atualizar vídeo, moderar comentário, inserir/reordenar playlist, agendar transmissão)	~50 unidades
Busca (playlists add --from-search)	~100 unidades/chamada
Upload (videos upload)	~1600 unidades

Antes de iniciar uma grande execução em lote (por exemplo, search-replace em centenas de vídeos, ou vários uploads), estime o custo e avise o usuário se ela puder esgotar a cota diária. Uma resposta quotaExceeded (HTTP 403) significa que o orçamento foi gasto até o próximo reinício; trabalhos de longa duração (videos upload) param de forma limpa e informam quantos foram bem-sucedidos para que possam ser retomados depois.

Fluxo de trabalho recomendado para um agente

1. Confirme a configuração uma vez com ytstudio status (e profile list se vários canais puderem estar em jogo). Selecione o canal com YTSTUDIO_PROFILE= ao fazer scripts.
2. Colete o estado com comandos de leitura usando -o json e analise o resultado.
3. Para qualquer alteração, execute o comando sem --execute primeiro, inspecione a pré-visualização e apresente-a ao usuário quando a alteração for relevante ou em lote.
4. Execute novamente o comando idêntico com --execute para aplicar.
5. Lembre-se da cota para operações em lote e upload.

Quando uma flag ou comportamento não estiver claro, consulte references/reference.md ou --help em vez de supor.