Skip to content

Command reference

Manage your YouTube channel from the terminal

Usage:

$ ytstudio [OPTIONS] COMMAND [ARGS]...

Options:

  • -v, --version: Show version
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, to copy it or customize the installation.
  • --help: Show this message and exit.

Commands:

  • init: Initialize with Google OAuth credentials
  • login: Authenticate with YouTube via OAuth
  • status: Show current authentication status
  • videos: Video management commands
  • analytics: Analytics commands
  • comments: Comment commands
  • livestreams: Live broadcast management (schedule,...
  • playlists: Playlist management commands
  • profile: Manage credential profiles (one per...

ytstudio init

Initialize with Google OAuth credentials

Usage:

$ ytstudio init [OPTIONS]

Options:

  • -c, --client-secrets TEXT: Path to Google OAuth client secrets JSON file
  • --help: Show this message and exit.

ytstudio login

Authenticate with YouTube via OAuth

Usage:

$ ytstudio login [OPTIONS]

Options:

  • --headless: Authenticate by pasting a redirect URL from another browser
  • --help: Show this message and exit.

ytstudio status

Show current authentication status

Usage:

$ ytstudio status [OPTIONS]

Options:

  • --help: Show this message and exit.

ytstudio videos

Video management commands

Usage:

$ ytstudio videos [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List your YouTube videos
  • show: Show details for a specific video
  • captions: List caption tracks for a video
  • transcript: Download a caption track as clean plain text
  • update: Update a video's metadata
  • search-replace: Bulk update videos using search and replace
  • categories: List YouTube video categories assignable...
  • upload: Upload one or more videos described by...

ytstudio videos list

List your YouTube videos

Usage:

$ ytstudio videos list [OPTIONS]

Options:

  • -n, --limit INTEGER: Number of videos to list [default: 20]
  • -p, --page-token TEXT: Page token for pagination
  • -s, --sort TEXT: Sort by: date, views, likes [default: date]
  • -o, --output TEXT: Output format: table, json, csv [default: table]
  • --audio-lang TEXT: Filter by audio language (e.g., en, nl)
  • --meta-lang TEXT: Filter by metadata language (e.g., en, nl)
  • --has-localization TEXT: Filter by available translation (e.g., en, nl)
  • --scheduled: Only show videos scheduled for future publish
  • --help: Show this message and exit.

ytstudio videos show

Show details for a specific video

Usage:

$ ytstudio videos show [OPTIONS] VIDEO_ID

Arguments:

  • VIDEO_ID: Video ID [required]

Options:

  • -o, --output TEXT: Output format: table, json [default: table]
  • --help: Show this message and exit.

ytstudio videos captions

List caption tracks for a video

Usage:

$ ytstudio videos captions [OPTIONS] VIDEO_ID

Arguments:

  • VIDEO_ID: Video ID [required]

Options:

  • -o, --output TEXT: Output format: table, json [default: table]
  • --help: Show this message and exit.

ytstudio videos transcript

Download a caption track as clean plain text

Usage:

$ ytstudio videos transcript [OPTIONS] VIDEO_ID

Arguments:

  • VIDEO_ID: Video ID [required]

Options:

  • --lang TEXT: Track language code (e.g. nl, en)
  • -o, --output TEXT: Output format: text, json [default: text]
  • --help: Show this message and exit.

ytstudio videos update

Update a video's metadata

Usage:

$ ytstudio videos update [OPTIONS] VIDEO_ID

Arguments:

  • VIDEO_ID: Video ID [required]

Options:

  • -t, --title TEXT: New title
  • -d, --description TEXT: New description
  • --tags TEXT: Comma-separated tags
  • --execute: Apply changes (default is dry-run)
  • --help: Show this message and exit.

ytstudio videos search-replace

Bulk update videos using search and replace

Usage:

$ ytstudio videos search-replace [OPTIONS]

Options:

  • -s, --search TEXT: Text to search for [required]
  • -r, --replace TEXT: Text to replace with [required]
  • -f, --field TEXT: Field to update: title, description [required]
  • --regex: Treat search as regex
  • -n, --limit INTEGER: Max matches to find [default: 10]
  • --execute: Apply changes (default is dry-run)
  • --help: Show this message and exit.

ytstudio videos categories

List YouTube video categories assignable to uploads

Usage:

$ ytstudio videos categories [OPTIONS]

Options:

  • -r, --region TEXT: Region code (ISO 3166-1 alpha-2) [default: US]
  • -o, --output TEXT: Output format: table, json [default: table]
  • --help: Show this message and exit.

ytstudio videos upload

Upload one or more videos described by yaml sidecars.

Usage:

$ ytstudio videos upload [OPTIONS] PATH

Arguments:

  • PATH: Video file or directory of videos with yaml sidecars [required]

Options:

  • --execute: Actually upload (default is dry-run)
  • -m, --max INTEGER: Maximum number of uploads in this run (0 = no limit) [default: 0]
  • --help: Show this message and exit.

ytstudio analytics

Analytics commands

Usage:

$ ytstudio analytics [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • overview: Get channel overview analytics
  • video: Get analytics for a specific video
  • query: Run a custom analytics query with any...
  • metrics: List available analytics metrics.
  • dimensions: List available analytics dimensions.

ytstudio analytics overview

Get channel overview analytics

Usage:

$ ytstudio analytics overview [OPTIONS]

Options:

  • -d, --days INTEGER: Number of days to analyze [default: 28]
  • --compare / --no-compare: Compare each metric to the previous equal-length window [default: compare]
  • -o, --output TEXT: Output format: table, json [default: table]
  • --help: Show this message and exit.

ytstudio analytics video

Get analytics for a specific video

Usage:

$ ytstudio analytics video [OPTIONS] VIDEO_ID

Arguments:

  • VIDEO_ID: Video ID [required]

Options:

  • -d, --days INTEGER: Number of days to analyze [default: 28]
  • -o, --output TEXT: Output format: table, json [default: table]
  • --help: Show this message and exit.

ytstudio analytics query

Run a custom analytics query with any metrics and dimensions.

Direct access to the YouTube Analytics API reports.query endpoint. Supports all available metrics and dimensions.

Examples:

ytstudio analytics query -m views,likes --dimensions day --days 7

ytstudio analytics query -m views,shares -d country --sort -views -n 10

ytstudio analytics query -m views,estimatedMinutesWatched -d video \
    --sort -views -n 5 --resolve -o json

ytstudio analytics query -m videoThumbnailImpressions,videoThumbnailImpressionsClickRate \
    -d video --sort -videoThumbnailImpressions -n 10

ytstudio analytics query -m views -d insightTrafficSourceType \
    -f video==dMH0bHeiRNg --sort -views

Usage:

$ ytstudio analytics query [OPTIONS]

Options:

  • -m, --metrics TEXT: Comma-separated metrics (e.g. views,likes,shares) [required]
  • -d, --dimensions TEXT: Comma-separated dimensions (e.g. day,country)
  • -f, --filter TEXT: Filter in key==value format (repeatable, e.g. -f video==ID -f country==NL)
  • -s, --start TEXT: Start date (YYYY-MM-DD). Defaults to --days ago
  • -e, --end TEXT: End date (YYYY-MM-DD). Defaults to today
  • --days INTEGER: Number of days (used if --start not set) [default: 28]
  • --sort TEXT: Sort field (prefix with - for descending)
  • -n, --limit INTEGER: Maximum number of rows
  • --currency TEXT: Currency code for revenue (e.g. EUR)
  • -o, --output TEXT: Output format: table, json, csv [default: table]
  • --raw: Show raw numbers instead of human-readable
  • --resolve: Resolve video/playlist dimension IDs to title columns
  • --help: Show this message and exit.

ytstudio analytics metrics

List available analytics metrics.

Examples:

ytstudio analytics metrics

ytstudio analytics metrics --group engagement

Usage:

$ ytstudio analytics metrics [OPTIONS]

Options:

  • -g, --group TEXT: Filter by group
  • -o, --output TEXT: Output format: table, json [default: table]
  • --help: Show this message and exit.

ytstudio analytics dimensions

List available analytics dimensions.

Examples:

ytstudio analytics dimensions

ytstudio analytics dimensions --group geographic

ytstudio analytics dimensions country

Usage:

$ ytstudio analytics dimensions [OPTIONS] [NAME]

Arguments:

  • [NAME]: Show details for a specific dimension

Options:

  • -g, --group TEXT: Filter by group
  • -o, --output TEXT: Output format: table, json [default: table]
  • --help: Show this message and exit.

ytstudio comments

Comment commands

Usage:

$ ytstudio comments [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List comments across channel or for a...
  • publish: Publish held comments (approve for public...
  • reject: Reject comments (hide from public display)
  • reply: Reply to a top-level comment.

ytstudio comments list

List comments across channel or for a specific video

Usage:

$ ytstudio comments list [OPTIONS]

Options:

  • -v, --video TEXT: Filter by video ID
  • --status [published|held|spam]: Moderation status: published, held, spam [default: published]
  • -n, --limit INTEGER: Number of comments [default: 20]
  • -s, --sort [relevance|time]: Sort order [default: time]
  • -o, --output TEXT: Output format: table, json [default: table]
  • --help: Show this message and exit.

ytstudio comments publish

Publish held comments (approve for public display)

Usage:

$ ytstudio comments publish [OPTIONS] COMMENT_IDS...

Arguments:

  • COMMENT_IDS...: Comment IDs to publish [required]

Options:

  • --help: Show this message and exit.

ytstudio comments reject

Reject comments (hide from public display)

Usage:

$ ytstudio comments reject [OPTIONS] COMMENT_IDS...

Arguments:

  • COMMENT_IDS...: Comment IDs to reject [required]

Options:

  • --ban: Also ban the comment author
  • --help: Show this message and exit.

ytstudio comments reply

Reply to a top-level comment.

Replies are flat on YouTube: COMMENT_ID must be a top-level comment id (the id shown by 'comments list'), not the id of another reply.

Usage:

$ ytstudio comments reply [OPTIONS] COMMENT_ID

Arguments:

  • COMMENT_ID: Top-level comment ID to reply to (from 'comments list') [required]

Options:

  • -t, --text TEXT: Reply text [required]
  • --help: Show this message and exit.

ytstudio livestreams

Live broadcast management (schedule, start, stop, update)

Usage:

$ ytstudio livestreams [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List your YouTube live broadcasts.
  • show: Show details for a specific broadcast.
  • start: Transition a broadcast to testing or live.
  • stop: Stop a live broadcast (transition to...
  • schedule: Schedule a new live broadcast.
  • update: Update a broadcast's metadata or settings...

ytstudio livestreams list

List your YouTube live broadcasts.

Usage:

$ ytstudio livestreams list [OPTIONS]

Options:

  • -s, --status [all|active|completed|upcoming]: Filter: all, upcoming, active, completed [default: upcoming]
  • -n, --limit INTEGER RANGE: Number of broadcasts [default: 20; 1<=x<=50]
  • -p, --page-token TEXT: Page token for pagination
  • -o, --output [table|json]: Output format: table or json [default: table]
  • --help: Show this message and exit.

ytstudio livestreams show

Show details for a specific broadcast.

Usage:

$ ytstudio livestreams show [OPTIONS] BROADCAST_ID

Arguments:

  • BROADCAST_ID: Broadcast ID [required]

Options:

  • --ingest: Also fetch and display the bound stream's ingest URL (key is redacted by default)
  • --show-key: Reveal the bound stream key (implies --ingest). Treat output as a secret.
  • -o, --output [table|json]: Output format: table or json [default: table]
  • --help: Show this message and exit.

ytstudio livestreams start

Transition a broadcast to testing or live.

Usage:

$ ytstudio livestreams start [OPTIONS] BROADCAST_ID

Arguments:

  • BROADCAST_ID: Broadcast ID [required]

Options:

  • --to [testing|live]: Target state: testing (monitor only) or live (publish to viewers). [default: live]
  • --help: Show this message and exit.

ytstudio livestreams stop

Stop a live broadcast (transition to complete).

Usage:

$ ytstudio livestreams stop [OPTIONS] BROADCAST_ID

Arguments:

  • BROADCAST_ID: Broadcast ID [required]

Options:

  • --help: Show this message and exit.

ytstudio livestreams schedule

Schedule a new live broadcast.

Usage:

$ ytstudio livestreams schedule [OPTIONS]

Options:

  • -t, --title TEXT: Broadcast title [required]
  • --scheduled-start TEXT: Scheduled start time, ISO 8601 (e.g. 2026-06-01T19:00:00+02:00) [required]
  • --scheduled-end TEXT: Scheduled end time, ISO 8601
  • -d, --description TEXT: Broadcast description
  • --privacy [public|private|unlisted]: public, private, or unlisted [default: public]
  • --made-for-kids / --not-made-for-kids: COPPA self-declaration; required by YouTube on every broadcast. [default: not-made-for-kids]
  • --execute: Create the broadcast (default is dry-run preview)
  • --help: Show this message and exit.

ytstudio livestreams update

Update a broadcast's metadata or settings (partial update).

Note: liveBroadcasts.update only accepts privacyStatus under status; the made-for-kids designation is set at schedule time and managed on the resulting video resource afterwards.

Usage:

$ ytstudio livestreams update [OPTIONS] BROADCAST_ID

Arguments:

  • BROADCAST_ID: Broadcast ID [required]

Options:

  • -t, --title TEXT: New title
  • -d, --description TEXT: New description
  • --privacy [public|private|unlisted]: New privacy status
  • --scheduled-start TEXT: New scheduled start, ISO 8601
  • --scheduled-end TEXT: New scheduled end, ISO 8601
  • --auto-start / --no-auto-start: Auto-start when stream begins
  • --auto-stop / --no-auto-stop: Auto-stop when stream ends
  • --dvr / --no-dvr: Enable DVR controls
  • --embed / --no-embed: Allow embedding
  • --record-from-start / --no-record-from-start: Record broadcast for archive
  • --closed-captions [closedCaptionsDisabled|closedCaptionsHttpPost|closedCaptionsEmbedded]: Closed-caption mode
  • --latency [normal|low|ultraLow]: Latency: normal, low, ultraLow
  • --projection [rectangular|360]: Projection: rectangular or 360
  • --execute: Apply changes (default is dry-run)
  • --help: Show this message and exit.

ytstudio playlists

Playlist management commands

Usage:

$ ytstudio playlists [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • list: List your playlists.
  • show: Show details for a specific playlist.
  • create: Create a new playlist.
  • update: Update a playlist's metadata.
  • delete: Delete a playlist.
  • items: List the items in a playlist.
  • add: Add videos to a playlist by ID or search...
  • remove: Remove items from a playlist by item id or...
  • reorder: Reorder a playlist by one of views, likes,...

ytstudio playlists list

List your playlists.

Usage:

$ ytstudio playlists list [OPTIONS]

Options:

  • -n, --limit INTEGER: Number of playlists to list [default: 50]
  • -p, --page-token TEXT: Page token for pagination
  • -s, --sort TEXT: Sort by: date, title, count [default: date]
  • -o, --output TEXT: Output format: table, json, csv [default: table]
  • --help: Show this message and exit.

ytstudio playlists show

Show details for a specific playlist.

Usage:

$ ytstudio playlists show [OPTIONS] PLAYLIST_ID

Arguments:

  • PLAYLIST_ID: Playlist ID [required]

Options:

  • -o, --output TEXT: Output format: table, json [default: table]
  • -i, --items: Also fetch and render the first 50 items
  • --help: Show this message and exit.

ytstudio playlists create

Create a new playlist.

Usage:

$ ytstudio playlists create [OPTIONS]

Options:

  • -t, --title TEXT: Playlist title [required]
  • -d, --description TEXT: Playlist description
  • --privacy TEXT: Privacy: private, public, unlisted [default: private]
  • --language TEXT: Default language tag (e.g. en, nl)
  • --execute: Create the playlist (default dry-run)
  • --help: Show this message and exit.

ytstudio playlists update

Update a playlist's metadata.

Usage:

$ ytstudio playlists update [OPTIONS] PLAYLIST_ID

Arguments:

  • PLAYLIST_ID: Playlist ID [required]

Options:

  • -t, --title TEXT: New title
  • -d, --description TEXT: New description
  • --privacy TEXT: New privacy: private, public, unlisted
  • --language TEXT: New default language
  • --execute: Apply changes (default is dry-run)
  • --help: Show this message and exit.

ytstudio playlists delete

Delete a playlist.

Usage:

$ ytstudio playlists delete [OPTIONS] PLAYLIST_ID

Arguments:

  • PLAYLIST_ID: Playlist ID [required]

Options:

  • --execute: Apply deletion (default is dry-run)
  • -y, --yes: Skip confirmation prompt
  • --help: Show this message and exit.

ytstudio playlists items

List the items in a playlist.

Usage:

$ ytstudio playlists items [OPTIONS] PLAYLIST_ID

Arguments:

  • PLAYLIST_ID: Playlist ID [required]

Options:

  • -n, --limit INTEGER: Number of items to list [default: 50]
  • -p, --page-token TEXT: Page token for pagination
  • -o, --output TEXT: Output format: table, json, csv [default: table]
  • --help: Show this message and exit.

ytstudio playlists add

Add videos to a playlist by ID or search query.

If --video is passed more than once, every ID is added. --from-search runs search().list(forMine=True, type=video, q=...) and adds up to --limit hits. Quota is 50 units per inserted video; a running counter is printed.

Usage:

$ ytstudio playlists add [OPTIONS] PLAYLIST_ID

Arguments:

  • PLAYLIST_ID: Playlist ID [required]

Options:

  • -v, --video TEXT: Video ID to add (repeatable)
  • --from-search TEXT: Add the top results from a search of your videos
  • -n, --limit INTEGER: Max videos to add per invocation (search mode) [default: 50]
  • --position INTEGER: Insert at this position
  • --note TEXT: Set contentDetails.note on each item
  • --execute: Apply changes (default is dry-run)
  • --help: Show this message and exit.

ytstudio playlists remove

Remove items from a playlist by item id or video id.

Usage:

$ ytstudio playlists remove [OPTIONS] PLAYLIST_ID

Arguments:

  • PLAYLIST_ID: Playlist ID [required]

Options:

  • -i, --item TEXT: Playlist item ID (PLPLI...) to remove (repeatable)
  • -v, --video TEXT: Video ID to remove (repeatable). Resolves to all playlist items for that video; duplicates are all removed.
  • --execute: Apply changes (default is dry-run)
  • --help: Show this message and exit.

ytstudio playlists reorder

Reorder a playlist by one of views, likes, published, title.

Usage:

$ ytstudio playlists reorder [OPTIONS] PLAYLIST_ID

Arguments:

  • PLAYLIST_ID: Playlist ID [required]

Options:

  • --by TEXT: Sort by: views, likes, published, title [default: views]
  • --order TEXT: Order: asc, desc [default: desc]
  • --execute: Apply changes (default is dry-run)
  • --help: Show this message and exit.

ytstudio profile

Manage credential profiles (one per YouTube channel)

Usage:

$ ytstudio profile [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • add: Authenticate a new profile and switch to it
  • list: List configured profiles
  • use: Switch the active profile
  • status: Show authentication status for a profile
  • remove: Remove a profile and its stored credentials
  • brand: Manage per-channel brand voice (brand.md)

ytstudio profile add

Authenticate a new profile and switch to it

Usage:

$ ytstudio profile add [OPTIONS] NAME

Arguments:

  • NAME: Name for the new profile [required]

Options:

  • --headless: Authenticate by pasting a redirect URL from another browser
  • --help: Show this message and exit.

ytstudio profile list

List configured profiles

Usage:

$ ytstudio profile list [OPTIONS]

Options:

  • --help: Show this message and exit.

ytstudio profile use

Switch the active profile

Usage:

$ ytstudio profile use [OPTIONS] NAME

Arguments:

  • NAME: Profile to make active [required]

Options:

  • --help: Show this message and exit.

ytstudio profile status

Show authentication status for a profile

Usage:

$ ytstudio profile status [OPTIONS] [NAME]

Arguments:

  • [NAME]: Profile name (default: active)

Options:

  • --help: Show this message and exit.

ytstudio profile remove

Remove a profile and its stored credentials

Usage:

$ ytstudio profile remove [OPTIONS] NAME

Arguments:

  • NAME: Profile to remove [required]

Options:

  • -f, --force: Skip confirmation
  • --help: Show this message and exit.

ytstudio profile brand

Manage per-channel brand voice (brand.md)

Usage:

$ ytstudio profile brand [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • show: Print the brand voice for a profile
  • set: Set brand voice non-interactively from a file
  • edit: Open the brand voice in $EDITOR

ytstudio profile brand show

Print the brand voice for a profile

Usage:

$ ytstudio profile brand show [OPTIONS]

Options:

  • -p, --profile TEXT: Profile (default: active)
  • --help: Show this message and exit.

ytstudio profile brand set

Set brand voice non-interactively from a file

Usage:

$ ytstudio profile brand set [OPTIONS]

Options:

  • -f, --file TEXT: Path to a markdown file to import [required]
  • -p, --profile TEXT: Profile (default: active)
  • --help: Show this message and exit.

ytstudio profile brand edit

Open the brand voice in $EDITOR

Usage:

$ ytstudio profile brand edit [OPTIONS]

Options:

  • -p, --profile TEXT: Profile (default: active)
  • --help: Show this message and exit.