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 YouTube Data API v3 and YouTube Analytics API. It supports script-friendly tables, JSON, JSON Lines, and TSV.

Public reads: search, channels and uploads, videos, playlists, comments, public subscriptions, live chat, and metadata.
Optional analytics: views, watch time, retention, subscribers, traffic sources, and demographics for the channel you authorize.
There are no write commands: no uploads, edits, moderation, or mutations.

Install

macOS / Linux

curl -fsSL https://davis7dotsh.github.io/open-yt-cli/install.sh | sh

The installer verifies SHA-256 checksums and needs no root access.

Windows (PowerShell)

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

Alternatively, download a ZIP from GitHub Releases.

From source

With Go 1.26+, clone the repository and run go install ./cmd/oytc, or use make build.

Getting started

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

oytc login
o ytc status --check

Use oytc status --check (without the space). Then make public-data requests:

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

Use oytc playlist items … (without the space). An API key is sufficient for all public commands. For ephemeral or CI use, OYTC_API_KEY takes precedence over a saved key.

Optional: your channel analytics

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

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

Use oytc analytics overview … (without the space). Analytics reports only on your authorized channel. Google accounts with Advanced Protection or restrictive Workspace policies may require verification for the sensitive youtube.readonly scope.

Every command

oytc --help, oytc <command> --help, and oytc <command> <subcommand> --help are the version-specific flag reference.

Credentials and maintenance

Command	What it does
`login`	Prompt for, validate, and save an API key.
`login --oauth`	Browser OAuth for read-only channel and Analytics access.
`status`	Show credential state without secrets.
`status --check`	Validate configured credentials remotely.
`logout`	Best-effort revoke OAuth and remove stored credentials.
`skills install` / `skill install`	With confirmation, install the bundled agent skill at `~/.agents/skills/oytc`.
`version`	Show version, commit, build date, and platform.
`update` / `upgrade`	Checksum-verified self-update. Use `--check` to report only or `--version vX.Y.Z` for an exact release.

Analytics (OAuth required)

Command	What it does
`analytics report --metrics CSV`	Run a raw report; optional `--dimensions`.
`analytics overview [--by day\|month]`	Views, watch time, retention, and 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 commands accept --start, --end, --filters, --sort, and --limit. Defaults cover the last 28 complete UTC days.

Public YouTube data (API key)

Command	What it does
`search [QUERY]`	Search videos, channels, and playlists; supports type, date, region, language, SafeSearch, and video-specific filters.
`channel get REFERENCE…`	Get channels by ID, `@handle`, or common channel 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, optionally by region/category.
`video trainability VIDEO_ID`	Read public AI-trainability; no API key or Data API quota required.
`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 specific threads.
`subscription list --channel CHANNEL_ID`	List public subscriptions when the channel exposes them.
`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, pagination, and limits

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

# newest public uploads for a script
ytc channel uploads @GoogleDevelopers --all --limit 100 --format jsonl

# video counters as TSV
ytc video stats dQw4w9WgXcQ --format tsv --columns id,statistics.viewCount

# owned-video analytics for January
ytc analytics video YOUR_OWN_VIDEO_ID --start 2026-01-01 --end 2026-01-31 --format json

Each example begins with oytc; the displayed examples’ missing o is corrected here: run oytc channel uploads …, oytc video stats …, and oytc analytics video ….

Search has a separate daily search-query quota; pagination consumes requests.
Analytics respects YouTube metric/dimension compatibility rules and only covers the authorized channel.
Live-chat streaming is REST polling, not the lower-latency gRPC stream method.
Owner-/partner-only features and all write operations are intentionally out of scope.

Complete source and version-specific documentation: davis7dotsh/open-yt-cli.