ytsh 0.2.0

CLI system for YouTube channel intelligence

ytsh — YouTube Intelligence Shell

ytsh is a small CLI for pulling YouTube channel + video + analytics data and storing it locally (SQLite), so you can query and reuse it.

Install

• From PyPI (recommended, once published):

pipx install ytsh

• Locally from this repo (same result as PyPI, no publish needed):

pipx install .

• From source (development):

pip install -e .

Shell completion is built in:

ytsh --install-completion

Quickstart

Initialize local storage (creates the SQLite database from the bundled schema):

ytsh init

This migrates any pre-existing data/youtube_ops.sqlite from an older repo-relative install into the standard data directory on first run.

Where things live:

• Data (SQLite DB + cache): ~/.local/share/ytsh (override with YTSH_DATA_HOME or XDG_DATA_HOME)
• Config (OAuth clients/tokens): ~/.config/ytsh (override with YTSH_CONFIG_HOME)

Add a YouTube channel using OAuth client credentials JSON:

ytsh channels add --client-creds /path/to/google-oauth-client.json

List added channels:

ytsh channels list

List latest videos for a channel (channel id like UC... or handle like @somehandle):

ytsh videos list --channel @somehandle --limit 10

Spy on any public channel using your most recently added OAuth token:

ytsh spy --channel @somehandle

Query YouTube Analytics (defaults to last 30 days, preset core metrics):

ytsh analytics query --channel @somehandle

Common options:

ytsh analytics query --channel @somehandle --days 7
ytsh analytics query --channel @somehandle --start-date 2026-01-01 --end-date 2026-01-31
ytsh analytics query --channel @somehandle --metrics core --dimensions video --sort -views --max-results 30
ytsh spy --channel @somehandle --period month --limit 20

Commands and options

ytsh (root)

ytsh --help

Global options:

• --install-completion: Install shell completion for the current shell
• --show-completion: Print the completion script for the current shell (so you can copy/customize it)

ytsh init

ytsh init

ytsh channels add

ytsh channels add --client-creds /path/to/google-oauth-client.json

Options:

• --client-creds TEXT (required): Path to Google OAuth client credentials JSON

ytsh channels list

ytsh channels list

ytsh videos list

ytsh videos list --channel @somehandle

Options:

• --channel TEXT (required): YouTube channel ID or channel handle
• --limit INTEGER (default: 10): Number of latest videos to return, 1-50
• --force-refresh: Ignore cache and fetch fresh data from YouTube
• --ttl-seconds INTEGER (default: 600): Cache freshness window in seconds
• --format TEXT (default: default): Output format

ytsh spy

ytsh spy --channel @somehandle

Returns a summary of the target public channel plus ranked popular/outlier videos for the selected time period. The target channel does not need to be added first, but ytsh must already have at least one active OAuth token from ytsh channels add.

Options:

• --channel TEXT (required): Public YouTube channel ID or channel handle
• --period TEXT (default: week): Ranking period (week, month, year, all)
• --limit INTEGER (default: 15): Number of ranked videos to return
• --force-refresh: Ignore cache and fetch fresh data from YouTube
• --ttl-seconds INTEGER (default: 600): Cache freshness window in seconds
• --format TEXT (default: default): Output format
• --max-fetch INTEGER (default: 200): Maximum uploads to scan when building the report

ytsh analytics query

ytsh analytics query --channel @somehandle

Options:

• --channel TEXT (required): YouTube channel ID or channel handle
• --days INTEGER: Date window ending today. Defaults to 30 when no explicit dates are supplied.
• --start-date TEXT: Start date in YYYY-MM-DD format. Use with --end-date.
• --end-date TEXT: End date in YYYY-MM-DD format. Use with --start-date.
• --metrics TEXT (default: core): Metric preset or comma-separated metrics
• --dimensions TEXT (default: empty): Comma-separated dimensions. Uses preset defaults when omitted.
• --filters TEXT (default: empty): Raw Analytics API filters string
• --sort TEXT (default: empty): Comma-separated sort expression. Uses preset defaults when omitted.
• --max-results INTEGER (default: 30): Maximum rows to return
• --force-refresh: Ignore cache and fetch fresh data from YouTube Analytics
• --ttl-seconds INTEGER (default: 600): Cache freshness window in seconds
• --format TEXT (default: default): Output format

Config

• Config directory: defaults to ~/.config/ytsh
• Override config directory: set YTSH_CONFIG_HOME (e.g. export YTSH_CONFIG_HOME=/some/path)
• Data directory: defaults to ~/.local/share/ytsh (or $XDG_DATA_HOME/ytsh)
• Override data directory: set YTSH_DATA_HOME

Help

ytsh --help
ytsh channels --help
ytsh videos --help
ytsh spy --help
ytsh analytics --help