oytc: Open YouTube CLI

A read-only command-line client for public YouTube data and, with optional authorization, analytics for your own channel.

What it does

oytc reads the YouTube Data API v3 and YouTube Analytics API. It has no upload, edit, moderation, or other write commands. It produces terminal tables by default and supports JSON, JSON Lines, and TSV for automation.

Public data: search, channels and uploads, videos, playlists, comments, public subscriptions, live chat, and metadata.
Optional OAuth: analytics for the channel that you authorize, including views, watch time, retention, subscribers, traffic sources, and demographics.

Install and get started

Install

# macOS / Linux — checksum-verified, no root needed
curl -fsSL https://davis7dotsh.github.io/open-yt-cli/install.sh | sh

# Windows PowerShell
irm https://davis7dotsh.github.io/open-yt-cli/install.ps1 | iex

You can also download a ZIP from GitHub Releases. From a clone with Go 1.26+, use go install ./cmd/oytc or make build.

Public-data setup

Create a Google Cloud project and enable YouTube Data API v3.
Create an API key restricted to that API.
Save and validate it; the secret prompt does not echo the key.

oytc login
o ytc status --check

Run oytc status --check—the command above should not contain a space. Then:

oytc search "Go conference" --type video --limit 5
oytc channel get @GoogleDevelopers
oytc video stats dQw4w9WgXcQ --format json
o ytc playlist items PLxxxx --all --limit 250

Run oytc playlist items …—the command above should not contain a space. OYTC_API_KEY is supported for ephemeral or CI use and takes precedence over a saved key.

Optional: your channel analytics

Configure a Google OAuth Desktop client, then authorize the read-only yt-analytics.readonly and youtube.readonly scopes.

oytc login --oauth
o ytc analytics overview --by day --format json

Run oytc analytics overview …—the command above should not contain a space. Analytics reports only on the authorized channel. Some protected accounts or Workspace policies require verification for the sensitive youtube.readonly scope.

Command reference

oytc --help, oytc <command> --help, and oytc <command> <subcommand> --help are authoritative for installed-version flags.

Credentials and maintenance

Command	Purpose
`login`	Prompt for, validate, and save a Data API key.
`login --oauth`	Browser OAuth for read-only channel and Analytics access.
`status` / `status --check`	Show safe credential state / also validate it remotely.
`logout`	Best-effort revoke OAuth and remove stored credentials.
`skills install` (`skill install`)	With confirmation, install the bundled agent skill to `~/.agents/skills/oytc`.
`version`	Show build and platform information.
`update` (`upgrade`)	Checksum-verified self-update; `--check` reports only and `--version` selects an exact tag.

Analytics — OAuth required

Command	Purpose
`analytics report --metrics CSV`	Raw report; optional `--dimensions`.
`analytics overview [--by day\|month]`	Views, watch time, retention, subscribers gained.
`analytics video VIDEO_ID`	Core metrics for one owned video.
`analytics traffic-sources`	Views and watch time by traffic source.
`analytics demographics`	Viewer percentage by age group and gender.

Analytics accepts --start, --end, --filters, --sort, and --limit; its default range is the latest 28 complete UTC days.

Public YouTube data — API key

Command	Purpose
`search [QUERY]`	Search videos, channels, and playlists with type, time, region, language, SafeSearch, and video filters.
`channel get REFERENCE…`	Get channels by ID, `@handle`, or common YouTube URL.
`channel activities CHANNEL`	List public channel activity.
`channel sections [CHANNEL]`	List sections, or fetch IDs with `--id`.
`channel uploads CHANNEL`	Resolve and enumerate the public uploads playlist.
`video get VIDEO_ID…`	Get metadata, content details, statistics, and status.
`video stats VIDEO_ID…`	Get public counters.
`video popular`	List the `mostPopular` chart by optional region/category.
`video trainability VIDEO_ID`	Read public AI-trainability; no API key or Data API quota needed.
`playlist get PLAYLIST_ID…`	Get playlists by ID.
`playlist list --channel CHANNEL_ID`	List a channel’s public playlists.
`playlist items PLAYLIST_ID`	List entries; optionally filter with `--video`.
`comment get COMMENT_ID…`	Get comments by ID.
`comment replies PARENT_COMMENT_ID`	List replies to a top-level comment.
`comment threads --video VIDEO_ID`	List threads on a video.
`comment threads --channel CHANNEL_ID`	List threads related to a channel.
`comment threads --id THREAD_IDS`	Get specified threads.
`subscription list --channel CHANNEL_ID`	List public subscriptions when exposed.
`subscription list --id SUBSCRIPTION_IDS`	Get public subscriptions by ID.
`live-chat list (--video VIDEO_ID \| --chat-id ID)`	Fetch one finite page of active public messages.
`live-chat stream (--video VIDEO_ID \| --chat-id ID)`	Continuously poll and deduplicate messages; JSONL by default.
`category list (--region REGION \| --id IDS)`	List video categories.
`language list`	List interface languages.
`region list`	List supported content regions.

Output and limits

All commands accept --format table|json|jsonl|tsv, --columns, --no-header, --quiet, and --timeout. Tables default on a terminal; JSON defaults when piped. Use --all deliberately on paginated lists and combine it with --limit for a hard cap.

Search has a separate daily quota and paging consumes requests.
Analytics obeys YouTube metric/dimension compatibility rules and is limited to the authorized channel.
Live-chat streaming uses REST polling, not the lower-latency gRPC stream method.
Owner-/partner-only features and all write operations are intentionally excluded.

Source and complete documentation: davis7dotsh/open-yt-cli.