yt_cli 3.0.2

A CLI tool for the YouTube Data, Live Streaming, and Analytics APIs.

yt_cli

A CLI tool for the YouTube Data, Live Streaming, and Analytics APIs.

Quick Start

Installation

# Using dart pub
dart pub global activate yt_cli

# Using homebrew
brew tap cdavis-code/yt
brew install --head yt       # latest development version (builds from source)
# or once a stable release is tagged:
brew install yt

Or download a pre-built binary from the releases page.

Publishing for Homebrew

The homebrew/ directory at the workspace root contains the canonical formula. To publish a new release:

1. Bump the version in pubspec.yaml and regenerate lib/meta.dart
2. Publish to pub.dev: dart pub publish
3. Push a version tag to trigger the binary build:

   git tag yt_cli-v2.2.7
   git push origin yt_cli-v2.2.7
   

4. Wait for the homebrew-release workflow to finish creating the GitHub Release
5. Run the Homebrew release script:

   dart run melos run homebrew
   

This downloads the source tarball, computes its SHA256, updates homebrew/yt.rb, and syncs the formula to the tap repo.

See homebrew/README.md for full tap setup and release documentation.

Usage

# Display all available commands
yt --help

# Search for videos
yt search list --q "flutter tutorial" --max-results 5

# List playlists for a channel
yt playlists list --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw --max-results 10

# View all subcommands for a command
yt videos --help

Features

• OAuth 2.0 web flow authorization with automatic token refresh
• Query channel activity events (uploads, likes, subscriptions, etc.)
• Query YouTube Analytics reports (views, watch time, demographics, and more)
• Manage analytics groups and group items for organizing channels, videos, or playlists
• Full CRUD for channels, playlists, videos, comments, and subscriptions
• Live broadcast and stream management with live chat interaction
• Channel members and membership levels
• Thumbnail and watermark management
• Video abuse report reasons lookup
• Cross-platform: runs on macOS, Linux, and Windows

Commands

Run yt --help for the full list. Key commands:

Command	Description
activities	List channel activity events
analytics	YouTube Analytics reports, groups, and group items
authorize	OAuth 2.0 web flow to authorize the CLI
broadcast	Manage live broadcasts
channels	Retrieve channel information
chat	Interact with live chat messages
comments	Manage YouTube comments
comment-threads	Manage comment threads
members	List channel members
memberships-levels	List membership pricing levels
playlists	Manage playlists
search	Search for videos, channels, and playlists
stream	Manage live streams
subscriptions	Manage channel subscriptions
thumbnails	Set thumbnail images
version	Display package name and version
videos	Manage videos (upload, update, delete)
video-categories	List video categories
video-abuse-report-reasons	List abuse report reasons
watermarks	Manage channel watermarks

Configuration

⚠️ Breaking Changes (v3.0.1)

OAuth token file format has changed. yt_cli v3.0.1 migrated from googleapis_auth to the cross-platform oauth2 package. yt authorize now writes access tokens via oauth2.Credentials.toJson().

If you have an existing tokens file (created by yt_cli < 3.0.0), you must re-authorize. Since the tokens file already exists, pass --overwrite-credentials (-o) to force a new flow:

yt authorize \
  --credentials-file ~/.yt/client_secrets.json \
  --tokens-file ~/.yt/access_tokens.json \
  --overwrite-credentials

Why? Previously, tokens were serialized in the googleapis_auth format (accessToken as an object with type, data, and expiry fields). The yt library now uses the oauth2 package format (accessToken as a plain string with separate expiration).

For full details, see the CHANGELOG.

---

YouTube API access requires either an API key (read-only) or OAuth 2.0 credentials.

Action Type	Authentication Requirement	Why
Reading Public Data	API Key or OAuth 2.0	Accesses data anyone can see (e.g., public video titles, search results).
Reading Private Data	OAuth 2.0 Required	Accesses data specific to a user (e.g., a user's private videos or watch history).
Writing/Modifying Data	OAuth 2.0 Required	Performs actions on behalf of a user (e.g., uploading, deleting, or commenting).

Authorization

Before using most commands, authorize the CLI with your YouTube account:

# 1. Download client_secret.json from Google Cloud Console
#    See: https://github.com/cdavis-code/yt_workspace/blob/main/packages/yt_cli/authentication.md

# 2. Run the authorization command
yt authorize

# Or specify a custom path to your credentials file
yt authorize --credentials-file ~/secrets/client_secret.json

The CLI starts a local HTTP server, opens an OAuth 2.0 page in your browser, and saves a permanent refresh token to youtube_server_tokens.json. Subsequent commands automatically refresh the access token in the background.

See authentication.md for step-by-step setup instructions.

Documentation

• Main Package Documentation
• Authentication Guide
• YouTube Data API Reference
• YouTube Live Streaming API Reference
• YouTube Analytics API Reference

Contributing

Any help from the open-source community is always welcome:

• Found an issue? Please fill a bug report with details.
• Need a feature? Open a feature request with use cases.
• Are you a developer? Fix a bug and send a pull request.

License

MIT License - see LICENSE for details.