@stophy/cli

@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