Skills youtube-analytics-cli

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/bin-huang/youtube-analytics-cli" ~/.claude/skills/clawdbot-skills-youtube-analytics-cli && rm -rf "$T"

manifest: skills/bin-huang/youtube-analytics-cli/SKILL.md

source content

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:

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

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

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.

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

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

# 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

# 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

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.

Skills youtube-analytics-cli

YouTube Analytics CLI Skill

Quick start

Authentication

Output format

Commands reference

channels

videos

report

Report examples

groups

group-items

Common YouTube Analytics dimensions

Common YouTube Analytics metrics

Workflow guidance

Quick channel overview

Deep video analysis

Audience analysis

Content strategy

Error handling

API documentation references