ytstudio
ytstudio는 YouTube Data 및 Analytics API를 위한 명령줄 도구입니다. YouTube Studio의 웹 UI에서 하나씩 클릭해야 하는 작업(대량 메타데이터 편집, 일괄 업로드, 스크립팅된 분석, 댓글 관리, 라이브 방송 제어, 재생목록 작업)을 대규모로 수행하기 위해 만들어졌습니다.
이 스킬은 이 도구를 사용하는 방법을 알려줍니다. 인터페이스에 얽매이지 않습니다. 모든 명령은 셸 명령입니다.
먼저 알아야 할 두 가지
이 두 가지 규칙은 거의 모든 명령에 적용되며 가장 흔한 실수를 방지합니다.
- JSON을 요청하세요. 읽기 명령은 기본적으로 사람이 읽기 쉬운 표를 출력합니다. 파싱 가능한 출력을 얻으려면
-o json(--output json)을 전달하세요. 일부 명령은-o csv도 지원합니다. auth/setup 명령(init,login,status)에는 JSON 모드가 없습니다. - 대부분의 변경 작업은 기본적으로 시뮬레이션 실행됩니다.
--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에서 이 앱을 확인하지 않았습니다" 경고에서 고급 -> 계속을 클릭하여 진행하세요.
- 요청된 모든 (읽기 전용) 범위를 승인하고 성공을 보고할 때까지 탭을 닫지 마세요.
자격 증명은 ~/.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 사이드카를 사용한 일괄 업로드
ytstudio videos upload <path>는 각 동영상 파일과 동일한 기본 이름의 YAML 사이드카 파일을 연결하고 모든 것을 검증한 후 업로드합니다. 기본적으로 시뮬레이션 실행됩니다. 사이드카 스키마(title, description, privacy, tags, category_id (필수), languages, 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가 없는 사이드카만 재시도합니다. 업로드는 할당량을 많이 소비하므로(약 1600단위) --max를 사용하여 실행을 제한하세요.
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는 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 # 거부 (+ 선택적 차단); 즉시 실행
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 # 수집 URL; 키는 숨김
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)은 정리되고 성공한 횟수를 보고하여 나중에 다시 시작할 수 있습니다.
에이전트 권장 워크플로우
ytstudio status(여러 채널이 있을 수 있는 경우profile list)로 설정을 한 번 확인하세요. 스크립팅할 때YTSTUDIO_PROFILE=을 사용하여 채널을 선택하세요.-o json과 함께 읽기 명령을 사용하여 상태를 수집하고 결과를 파싱하세요.- 변경 사항의 경우
--execute없이 명령을 먼저 실행하고 미리보기를 검사하여 변경 사항이 중요하거나 대량인 경우 사용자에게 보여주세요. - 동일한 명령을
--execute와 함께 다시 실행하여 적용하세요. - 대량 및 업로드 작업의 경우 할당량을 염두에 두세요.
플래그나 동작이 명확하지 않은 경우 추측하지 말고 references/reference.md 또는 --help를 참조하세요.