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#

bash

# 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:

bash

npm install -g youtube-analytics-cli

Authentication#

The CLI supports two authentication methods:

MethodUse caseCommandsAPI keyPublic data (channels, videos)channels <id>, videosOAuth 2.0Private data + analyticsAll commands (required for report, groups, group-items, channels without ID)

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:

json

{
  "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).

bash

# 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

Options:

• --part <parts> -- parts to include (default: snippet,statistics,contentDetails)

When no channel ID is provided, the command uses mine=true which requires OAuth authentication.

videos#

Get video details by IDs. Accepts one or more comma-separated video IDs.

bash

# Single video
youtube-analytics-cli videos dQw4w9WgXcQ

# Multiple videos
youtube-analytics-cli videos dQw4w9WgXcQ,jNQXAC9IVRw

# Request specific parts
youtube-analytics-cli videos dQw4w9WgXcQ --part snippet,statistics,contentDetails

Options:

• --part <parts> -- parts to include (default: snippet,statistics,contentDetails)

report#

Run a YouTube Analytics report. Requires OAuth.

bash

youtube-analytics-cli report \
  --metrics <metrics> \
  --start-date <YYYY-MM-DD> \
  --end-date <YYYY-MM-DD> \
  [--dimensions <dims>] \
  [--filters <filters>] \
  [--sort <sort>] \
  [--max-results <n>] \
  [--ids <ids>] \
  [--currency <code>]

Required options:

• --metrics <metrics> -- metrics to retrieve (e.g. views,likes,subscribersGained)
• --start-date <date> -- start date in YYYY-MM-DD format
• --end-date <date> -- end date in YYYY-MM-DD format

Optional options:

• --dimensions <dims> -- dimensions (e.g. day, video, country)
• --filters <filters> -- filters (e.g. video==VIDEO_ID;country==US)
• --sort <sort> -- sort order (e.g. -views for descending)
• --max-results <n> -- max rows to return
• --ids <ids> -- channel or content owner (default: channel==MINE)
• --currency <code> -- currency code (e.g. USD)

Report examples

Daily views and engagement for the last 30 days:

bash

youtube-analytics-cli report \
  --metrics views,likes,subscribersGained \
  --start-date 2026-02-17 \
  --end-date 2026-03-19 \
  --dimensions day

Top videos by views:

bash

youtube-analytics-cli report \
  --metrics views,estimatedMinutesWatched,averageViewDuration \
  --start-date 2026-01-01 \
  --end-date 2026-03-19 \
  --dimensions video \
  --sort -views \
  --max-results 10

Country breakdown:

bash

youtube-analytics-cli report \
  --metrics views,likes,estimatedMinutesWatched \
  --start-date 2026-01-01 \
  --end-date 2026-03-19 \
  --dimensions country \
  --sort -views \
  --max-results 20

Country breakdown for a specific video:

bash

youtube-analytics-cli report \
  --metrics views,likes \
  --start-date 2026-01-01 \
  --end-date 2026-03-19 \
  --dimensions country \
  --filters video==dQw4w9WgXcQ

Traffic source breakdown:

bash

youtube-analytics-cli report \
  --metrics views,estimatedMinutesWatched \
  --start-date 2026-01-01 \
  --end-date 2026-03-19 \
  --dimensions insightTrafficSourceType \
  --sort -views

Device type breakdown:

bash

youtube-analytics-cli report \
  --metrics views,estimatedMinutesWatched \
  --start-date 2026-01-01 \
  --end-date 2026-03-19 \
  --dimensions deviceType \
  --sort -views

Subscriber changes by day:

bash

youtube-analytics-cli report \
  --metrics subscribersGained,subscribersLost \
  --start-date 2026-02-17 \
  --end-date 2026-03-19 \
  --dimensions day

Revenue report (content owner reports only -- may not work with channel==MINE):

bash

youtube-analytics-cli report \
  --metrics estimatedRevenue,estimatedAdRevenue,grossRevenue \
  --start-date 2026-01-01 \
  --end-date 2026-03-19 \
  --dimensions day \
  --currency USD

groups#

List YouTube Analytics groups. Requires OAuth. Supports pagination via --next-page-token.

bash

# List all your groups
youtube-analytics-cli groups

# Get a specific group by ID
youtube-analytics-cli groups --id GROUP_ID

# Paginate through results
youtube-analytics-cli groups --next-page-token TOKEN

Options:

• --id <id> -- group ID(s) to retrieve (comma-separated)
• --next-page-token <token> -- pagination token

When no --id is provided, the command uses mine=true to list the authenticated user's groups.

group-items#

List items in a YouTube Analytics group. Requires OAuth. Supports pagination via --next-page-token.

bash

# List items in a group
youtube-analytics-cli group-items GROUP_ID

# Paginate through results
youtube-analytics-cli group-items GROUP_ID --next-page-token TOKEN

Options:

• --next-page-token <token> -- pagination token

Common YouTube Analytics dimensions#

Time: day, month

Content: video, playlist, channel (content owner reports only)

Geography: country, province, continent (filter-only), subContinent (filter-only)

Traffic source: insightTrafficSourceType, insightTrafficSourceDetail

Device: deviceType, operatingSystem

Playback: liveOrOnDemand, subscribedStatus, youtubeProduct

Demographics: ageGroup, gender

Sharing: sharingService

Annotations (deprecated since 2019): annotationType, annotationId

Cards: cardType, cardId

End screens: endScreenElementType, endScreenElementId

Common YouTube Analytics metrics#

Views and engagement: views, likes, dislikes, comments, shares

Watch time: estimatedMinutesWatched, averageViewDuration, averageViewPercentage

Subscribers: subscribersGained, subscribersLost

Revenue (monetized channels): estimatedRevenue, estimatedAdRevenue, grossRevenue, estimatedRedPartnerRevenue, monetizedPlaybacks, adImpressions, cpm

Cards: cardImpressions, cardClicks, cardClickRate

Annotations (deprecated -- historical data only, annotations removed from YouTube in 2019): annotationImpressions, annotationClicks, annotationClickThroughRate, annotationClosableImpressions, annotationCloseRate

End screens: endScreenElementImpressions, endScreenElementClicks, endScreenElementClickRate

Workflow guidance#

Quick channel overview#

1. Run youtube-analytics-cli channels to get your channel's current stats
2. Run a report with --dimensions day and key metrics ( views,likes,subscribersGained,estimatedMinutesWatched) for the last 30 days
3. Run a per-video breakdown to find top-performing content

Deep video analysis#

1. Start broad: per-video views and watch time for the period
2. Drill down: pick a specific video and break down by country, insightTrafficSourceType, or deviceType
3. Use --filters video==VIDEO_ID to isolate a single video
4. Compare date ranges by running the same report for different periods

Audience analysis#

1. Run a report with --dimensions country to see geographic distribution
2. Use --dimensions ageGroup,gender for demographics
3. Use --dimensions subscribedStatus to compare subscriber vs non-subscriber engagement

Content strategy#

1. Get per-video stats with --dimensions video --sort -views --max-results 20
2. Check traffic sources with --dimensions insightTrafficSourceType
3. Compare estimatedMinutesWatched across videos to identify engaging content
4. Track subscribersGained to see which content drives subscriptions

Error handling#

• OAuth credentials required -- the command needs client_id, client_secret, and refresh_token. API key alone is not sufficient for analytics commands.
• Token refresh failed -- the refresh token may be expired or revoked. The user needs to re-authorize and obtain a new refresh token.
• No credentials found -- provide credentials via --credentials, environment variables, or ~/.config/youtube-analytics-cli/credentials.json.
• HTTP 403 Forbidden -- the OAuth scopes may be insufficient, or the YouTube Analytics API may not be enabled in the Google Cloud project.
• Empty results -- check date range, metrics/dimensions compatibility, and whether the channel has data for the requested period.

API documentation references#

• youtube-analytics-cli documentation
• YouTube Data API v3
• YouTube Analytics API v2
• YouTube Analytics reports
• YouTube Analytics dimensions
• YouTube Analytics metrics
• YouTube Analytics groups
• YouTube Analytics group items