YouTube Analytics CLI Skill

You have access to youtube-analytics-cli, a read-only CLI for the YouTube Data API v3 and YouTube Analytics API v2. Use it to fetch channel and video details, run analytics reports, and manage analytics groups.

Quick start

# Check if the CLI is available
youtube-analytics-cli --help

# Get a channel's public data (API key sufficient)
youtube-analytics-cli channels UCxxxxxxxxxxxxxx

# Get your own channel (OAuth required)
youtube-analytics-cli channels

If the CLI is not installed, install it:

npm install -g youtube-analytics-cli

Authentication

The CLI supports two authentication methods:

Credentials are resolved in this order:

1. --credentials <path> flag (per-command)
2. YOUTUBE_API_KEY, YOUTUBE_CLIENT_ID, YOUTUBE_CLIENT_SECRET, YOUTUBE_REFRESH_TOKEN env vars
3. ~/.config/youtube-analytics-cli/credentials.json (auto-detected)

The credentials JSON file supports these fields:

{
  "api_key": "YOUR_API_KEY",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

The file must contain at least api_key or client_id. OAuth commands require all three OAuth fields (client_id, client_secret, refresh_token).

Important: Service accounts do NOT work with YouTube APIs. You must use OAuth 2.0 with a refresh token. Required scopes:

• https://www.googleapis.com/auth/youtube.readonly
• https://www.googleapis.com/auth/yt-analytics.readonly
• https://www.googleapis.com/auth/yt-analytics-monetary.readonly (for revenue metrics -- note: revenue metrics may only be available for content owner reports, not standard channel reports)

Before running analytics commands, verify OAuth credentials by running youtube-analytics-cli channels (no ID). If it fails, ask the user to set up OAuth 2.0 credentials.

Output format

All commands output pretty-printed JSON by default. Use --format compact for single-line JSON.

Global options:

• --format <format> -- json (default, pretty-printed) or compact (single-line)
• --credentials <path> -- path to credentials JSON file

Errors are written to stderr as JSON with an error field and a non-zero exit code.

Commands reference

channels

Get channel details. Omit the channel ID to get the authenticated user's own channel (requires OAuth).

# Get a specific channel by ID (API key sufficient)
youtube-analytics-cli channels UCxxxxxxxxxxxxxx

# Get your own channel (OAuth required)
youtube-analytics-cli channels

# Request specific parts
youtube-analytics-cli channels UCxxxxxxxxxxxxxx --part snippet,statistics,brandingSettings