| name | youtube-analytics-cli |
| description | YouTube channel statistics, video data, and analytics reporting via youtube-analytics-cli. Use when the user wants to check YouTube channel stats, video performance, run analytics reports with dimensions and filters, or manage analytics groups. Triggers: "YouTube Analytics", "YouTube", "channel stats", "video views", "subscribers", "watch time", "YouTube report", "estimated minutes watched", "YouTube groups".
|
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
youtube-analytics-cli --help
youtube-analytics-cli channels UCxxxxxxxxxxxxxx
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:
| Method | Use case | Commands |
|---|
| API key | Public data (channels, videos) | channels <id>, videos |
| OAuth 2.0 | Private data + analytics | All commands (required for report, groups, group-items, channels without ID) |
Credentials are resolved in this order:
--credentials <path> flag (per-command)YOUTUBE_API_KEY, YOUTUBE_CLIENT_ID, YOUTUBE_CLIENT_SECRET, YOUTUBE_REFRESH_TOKEN env vars~/.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.readonlyhttps://www.googleapis.com/auth/yt-analytics.readonlyhttps://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).
youtube-analytics-cli channels UCxxxxxxxxxxxxxx
youtube-analytics-cli channels
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.
youtube-analytics-cli videos dQw4w9WgXcQ
youtube-analytics-cli videos dQw4w9WgXcQ,jNQXAC9IVRw
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.
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:
youtube-analytics-cli report \
--metrics views,likes,subscribersGained \
--start-date 2026-02-17 \
--end-date 2026-03-19 \
--dimensions day
Top videos by views:
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:
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:
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:
youtube-analytics-cli report \
--metrics views,estimatedMinutesWatched \
--start-date 2026-01-01 \
--end-date 2026-03-19 \
--dimensions insightTrafficSourceType \
--sort -views
Device type breakdown:
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:
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):
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.
youtube-analytics-cli groups
youtube-analytics-cli groups --id GROUP_ID
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.
youtube-analytics-cli group-items GROUP_ID
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
- Run
youtube-analytics-cli channels to get your channel's current stats
- Run a report with
--dimensions day and key metrics (views,likes,subscribersGained,estimatedMinutesWatched) for the last 30 days
- Run a per-video breakdown to find top-performing content
Deep video analysis
- Start broad: per-video views and watch time for the period
- Drill down: pick a specific video and break down by
country, insightTrafficSourceType, or deviceType
- Use
--filters video==VIDEO_ID to isolate a single video
- Compare date ranges by running the same report for different periods
Audience analysis
- Run a report with
--dimensions country to see geographic distribution
- Use
--dimensions ageGroup,gender for demographics
- Use
--dimensions subscribedStatus to compare subscriber vs non-subscriber engagement
Content strategy
- Get per-video stats with
--dimensions video --sort -views --max-results 20
- Check traffic sources with
--dimensions insightTrafficSourceType
- Compare
estimatedMinutesWatched across videos to identify engaging content
- 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
