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 from YouTube Data API v3 and YouTube Analytics API. It is designed for scripts as well as interactive terminal use: tables on a terminal by default and JSON when output is piped.

Public data: search, channels, uploads, videos, playlists, comments, public subscriptions, live chat, and YouTube metadata.
Channel analytics: views, watch time, retention, subscriber gains, traffic sources, and demographic breakdowns for the channel you authorize.
Safety boundary: it has no upload, edit, moderation, or other write commands. OAuth is read-only.

Install

macOS or Linux

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

The installer verifies SHA-256 checksums and does not require root access.

Windows

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

You can also download a ZIP from GitHub Releases.

From source

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

Getting started

Create a Google Cloud project, enable YouTube Data API v3, and create an API key restricted to that API.
Save and validate the key. The command prompts without echoing the secret.

oytc login
o ytc status --check

Corrected command: use oytc status --check (without the space shown in the illustrative line above).

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

Corrected commands: use oytc channel get … and oytc video stats ….

For public data only, this API-key setup is sufficient. OYTC_API_KEY can be used for ephemeral/CI use and takes precedence over the 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

Corrected command: use oytc analytics overview …. Analytics commands only report on the channel you authorize. Some protected Google accounts or Workspace policies require verification of an app requesting the sensitive youtube.readonly scope.

Command reference

Use oytc --help, oytc <command> --help, or oytc <command> <subcommand> --help for the flags in your installed version.

Credentials and maintenance

Command	Purpose
`login`	Prompt for, validate, and save a YouTube Data API key.
`login --oauth`	Run browser OAuth for read-only access to your channel and Analytics.
`status`	Show local credential configuration without revealing secrets.
`status --check`	Validate each configured credential remotely.
`logout`	Best-effort revoke OAuth and remove stored credentials.
`version`	Show version, commit, build date, and platform.
`update` / `upgrade`	Checksum-verified self-update from GitHub Releases; use `--check` to only report, or `--version vX.Y.Z` to choose a release.
`skills install` / `skill install`	With confirmation, install the bundled agent skill at `~/.agents/skills/oytc`.

Analytics (OAuth required)

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

All analytics reports accept --start, --end, --filters, --sort, and --limit. Dates default to the last 28 complete UTC days.

Public YouTube data (API key)

Command	Purpose
`search [QUERY]`	Search videos, channels, and playlists. Supports type, date, region, language, SafeSearch, and video-specific filters.
`channel get REFERENCE…`	Look up channels by ID, `@handle`, or common YouTube channel URL.
`channel activities CHANNEL`	List public channel activity.
`channel sections [CHANNEL]`	List channel sections, or fetch specified IDs with `--id`.
`channel uploads CHANNEL`	Resolve and enumerate the channel’s public uploads playlist; use `--all` and `--limit` for a full bounded scan.
`video get VIDEO_ID…`	Fetch video metadata, content details, statistics, and status.
`video stats VIDEO_ID…`	Fetch public counters such as views, likes, and comments.
`video popular`	List the `mostPopular` chart, optionally by `--region` and `--category`.
`video trainability VIDEO_ID`	Read the public AI-trainability result; it does not need an API key or consume Data API quota.
`playlist get PLAYLIST_ID…`	Fetch playlists by ID.
`playlist list --channel CHANNEL_ID`	List a channel’s public playlists.
`playlist items PLAYLIST_ID`	List playlist entries; optionally filter with `--video`.
`comment get COMMENT_ID…`	Fetch 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`	Fetch specific comment threads.
`subscription list --channel CHANNEL_ID`	List a channel’s public subscriptions, when the channel exposes them.
`subscription list --id SUBSCRIPTION_IDS`	Fetch public subscriptions by ID.
`live-chat list (--video VIDEO_ID \| --chat-id ID)`	Fetch one finite page of active public live-chat messages.
`live-chat stream (--video VIDEO_ID \| --chat-id ID)`	Poll and emit deduplicated live-chat messages continuously; JSONL is the default.
`category list (--region REGION \| --id IDS)`	List video categories for a region or specified IDs.
`language list`	List YouTube interface languages.
`region list`	List supported content regions.

Shared output, pagination, and practical examples

Every command supports --format table|json|jsonl|tsv, --columns, --no-header, --quiet, and --timeout. Tables are the default on a terminal; JSON is the default when piped. Use --all deliberately for paginated lists and pair it with --limit when you want a hard cap.

# newest public uploads, ready for script processing
oytc channel uploads @GoogleDevelopers --all --limit 100 --format jsonl

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

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

Corrected command: the final example begins oytc analytics video ….

Important limits

Public commands require a valid API key except video trainability. Search has a separate daily search-query quota, and paging consumes requests.
analytics requires OAuth and reports only on the authorized channel. YouTube’s metric/dimension compatibility rules determine valid report combinations.
Live-chat streaming is REST polling, not the lower-latency gRPC stream method.
The CLI intentionally excludes write operations and owner-/partner-only features such as uploads, moderation, captions, memberships, and revenue reporting.

Project source and the complete, version-specific reference: davis7dotsh/open-yt-cli.