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,...
  • 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
  • update: Update a video's metadata
  • search-replace: Bulk update videos using search and replace
  • 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 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 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]
  • -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 -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
  • --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)

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 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 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

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.