@stophy/cli

YouTube context for AI agents. Search, transcripts, comments, channels, playlists — structured JSON from the terminal.

Quick start

Install the CLI globally, add every Stophy skill to all supported AI agents, and authenticate in your browser:

npx -y @stophy/cli@latest init --all --browser

Install

npm install -g @stophy/cli

Or install a standalone binary (no Node.js required):

# macOS / Linux
curl -fsSL https://stophy.dev/install.sh | bash

# Windows (PowerShell)
irm https://stophy.dev/install.ps1 | iex

# Homebrew
brew install stophydotdev/tap/stophy

The npm package requires Node.js 18 or later. Get an API key at stophy.dev.

Auth

stophy login --browser           # opens browser
stophy login --api-key st_xxx    # paste key directly
export STOPHY_API_KEY="st_..."   # env var also works

Commands

search

stophy search --q "typescript tutorial" --type video --sortBy viewCount
stophy search --q "next.js" --uploadDate week --duration long

video details

stophy video details --url "https://youtube.com/watch?v=QRvfjPltvmE"

{
  "video": {
    "id": "QRvfjPltvmE",
    "title": "TraRags Reacts To Kendrick Lamar - GNX",
    "author": "TRA RAGS STREAMS",
    "viewCount": 204828,
    "likeCount": 9170,
    "durationText": "2 hours 42 minutes 27 seconds",
    "publishedAt": "2024-11-23T08:22:36.000Z"
  },
  "related": [
    { "id": "h6ukrWyqOm4", "title": "...", "author": "...", "viewCount": 12000 }
  ]
}

video transcript

stophy video transcript --url "https://youtube.com/watch?v=..."

{
  "videoId": "QRvfjPltvmE",
  "language": { "code": "en", "name": "English", "isAutoGenerated": true },
  "segments": [
    { "text": "what is up everybody", "start": 0.0, "duration": 1.96 },
    { "text": "welcome back to the channel", "start": 1.96, "duration": 2.0 }
  ],
  "text": "what is up everybody welcome back to the channel"
}

video comments

stophy video comments --url "https://youtube.com/watch?v=QRvfjPltvmE" --sortBy top

{
  "items": [
    { "text": "\"Nah, that's not enough\" 😂", "author": "@terribletimes902", "likeCount": 2100 },
    { "text": "53:15 BRO CREAMED HIMSELF LIVE 😭😭😭😭", "author": "@Aunos1", "likeCount": 593 },
    { "text": "WHO ELSE BACK TO THIS AFTER THE ICEMAN REACTION?? 🙌🏾✊🏾", "author": "@colouredhearts", "likeCount": 134 }
  ],
  "continuationToken": "..."
}

video livechat

stophy video livechat --url "https://youtube.com/watch?v=..." --chat-type top

{
  "status": "live",
  "concurrentViewers": 1234,
  "pollIntervalMs": 10000,
  "messages": [
    { "text": "first!", "author": "@viewer1", "isModerator": false, "superChatAmount": null }
  ],
  "continuationToken": "..."
}

channel

stophy channel --url "https://youtube.com/@t3dotgg" --tab video --sortBy popular

{
  "channel": {
    "name": "Theo - t3.gg",
    "handle": "@t3dotgg",
    "subscriberCount": "539K subscribers",
    "videoCount": "1K videos",
    "isVerified": true
  },
  "items": [
    { "title": "PirateSoftware is right, this needs to stop", "viewCount": 1000000, "duration": "15:14" }
  ]
}

playlist

stophy playlist --url "https://youtube.com/playlist?list=PLxxxx"

usage and logs

stophy usage --days 7
stophy logs --days 30 --endpoint /v1/video

All commands

| Command | What it does | |---------|-------------| | stophy init --all --browser | Install the CLI, all agent skills, and authenticate | | stophy login | Authenticate with API key or browser | | stophy search | Search YouTube by keyword | | stophy suggest | Search autocomplete suggestions | | stophy video details | Video metadata | | stophy video transcript | Timestamped transcript | | stophy video comments | Paginated comments | | stophy video replies | Comment replies | | stophy video livechat | Livestream chat messages and status | | stophy channel | Channel videos, Shorts, playlists, or about page | | stophy playlist | Playlist videos and metadata | | stophy credits | Remaining credit balance | | stophy usage | API usage for your key | | stophy logs | Request logs for your key | | stophy status | Version, auth status, and credit balance | | stophy doctor | Diagnose install, auth, and API connectivity | | stophy version | CLI version and auth status | | stophy view-config | Config and auth status | | stophy logout | Clear saved credentials |

The CLI checks npm for a newer version in the background and prints a one-line notice when an update is available. Set STOPHY_NO_UPDATE_CHECK=1 to disable it.

Each command supports --help. Full docs at docs.stophy.dev.

Also see

• @stophy/mcp — MCP server for AI agents
• stophydotdev/skills — agent skills for the CLI (npx skills add stophydotdev/skills)
• stophy.dev — dashboard and API keys

License

MIT