CLI

@stophy/cli is a CLI for the Stophy API. Search, transcripts, comments, channels, playlists. All output goes to stdout as JSON.

Install

npm install -g @stophy/cli

Requires Node.js 18 or later.

Authentication

stophy login                        # interactive — browser or API key
stophy login --browser              # open browser directly
stophy login --api-key st_xxx       # paste key directly
export STOPHY_API_KEY="st_..."      # or set env var

Get your API key from stophy.dev/dashboard.

Environment variable

If STOPHY_API_KEY is set, the CLI uses it automatically. No login required. Useful in CI/CD and scripts.

STOPHY_API_KEY=st_xxx stophy search --q "typescript"

Commands

search

Search YouTube by keyword with filters for type, date, duration, and sort order.

stophy search --q "typescript tutorial"
stophy search --q "next.js" --type video --sortBy viewCount
stophy search --q "AI news" --uploadDate today --duration short
stophy search --q "python" --continuation-token <token>

Options

Option	Values	Description
`--q <query>`	any	Search query (required)
`--type <type>`	video, channel, playlist	Content type filter
`--sortBy <sort>`	relevance, uploadDate, viewCount, rating	Sort order
`--uploadDate <date>`	hour, today, week, month, year	Upload recency
`--duration <duration>`	short, medium, long	Under 4 min / 4–20 min / over 20 min
`--continuation-token`	string	Fetch the next page of results
`--json`	—	Print raw JSON

suggest

Get YouTube autocomplete suggestions for a partial query.

stophy suggest --q "how to"
stophy suggest --q "typescript" --hl en --gl US

Options

Option	Values	Description
`--q <query>`	any	Partial search query (required)
`--hl <lang>`	e.g. `en`, `fr`	Language code (default: en)
`--gl <country>`	e.g. `US`, `FR`	Country code (default: US)
`--json`	—	Print raw JSON

video details

Get metadata for a YouTube video: title, views, description, channel, thumbnails.

stophy video details --url "https://www.youtube.com/watch?v=h6ukrWyqOm4"
stophy video details --url "https://www.youtube.com/watch?v=h6ukrWyqOm4" --json | jq '.data.title'

video transcript

Get the full transcript with timestamps.

stophy video transcript --url "https://www.youtube.com/watch?v=h6ukrWyqOm4"
stophy video transcript --url "https://www.youtube.com/watch?v=h6ukrWyqOm4" --json | jq '.data.segments[].text'

video comments

Get comments for a video, sorted by top or latest. Supports pagination.

stophy video comments --url "https://www.youtube.com/watch?v=h6ukrWyqOm4"
stophy video comments --url "https://www.youtube.com/watch?v=h6ukrWyqOm4" --sortBy top
stophy video comments --url "https://www.youtube.com/watch?v=h6ukrWyqOm4" --continuation-token <token>

Options

Option	Values	Description
`--url <url>`	YouTube video URL	Required
`--sortBy <sort>`	top, latest	Comment sort order
`--continuation-token`	string	Fetch the next page
`--json`	—	Print raw JSON

video replies

Get replies to a comment using the repliesToken from a comments response.

stophy video replies --continuation-token "<repliesToken>"

channel

Browse a channel's videos, shorts, playlists, or about page.

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

Options

Option	Values	Description
`--url <url>`	YouTube channel URL or @handle	Required
`--tab <tab>`	video, short, playlist, about	Which tab to fetch (default: video)
`--sortBy <sort>`	latest, popular, oldest	Sort order. Only applies with `--tab video`.
`--continuation-token`	string	Fetch the next page
`--json`	—	Print raw JSON

playlist

Get all videos in a playlist with full metadata.

stophy playlist --url "https://www.youtube.com/playlist?list=PLxxxxxx"
stophy playlist --url "https://www.youtube.com/playlist?list=PLxxxxxx" --json | jq '.data.videos[].title'

credits

Check your remaining credit balance. Free. Doesn't cost a credit.

stophy credits
# Credits remaining: 39142

stophy credits --json

usage

Show API usage for your key over a time range.

stophy usage
stophy usage --days 30
stophy usage --days today --json

Options

Option	Values	Description
`--days <days>`	today, 7, 30	Time range (default: 7)
`--json`	—	Print raw JSON

logs

Show request logs for your key.

stophy logs
stophy logs --days 30 --endpoint /v1/search

Options

Option	Values	Description
`--days <days>`	today, 7, 30	Time range (default: 7)
`--endpoint <endpoint>`	e.g. `/v1/search`	Filter by endpoint
`--json`	—	Print raw JSON

view-config

Show your current config and auth status.

stophy view-config

logout

Clear saved credentials.

stophy logout

Piping output

All commands output JSON to stdout. Status messages and prompts go to stderr so piping works cleanly.

# Extract just the titles from search results
stophy search --q "react tutorial" --json | jq '.data.results[].title'

# Get transcript text as plain string
stophy video transcript --url "https://www.youtube.com/watch?v=h6ukrWyqOm4" --json \
  | jq '.data.segments[].text' -r | tr '\n' ' '

# Pipe channel videos into another command
stophy channel --url "https://www.youtube.com/@t3dotgg" --json \
  | jq '.data.items[].url' -r

Config file

Credentials and settings are stored at:

Linux / macOS: ~/.config/stophy/config.json
Windows: %APPDATA%\stophy\config.json

The file is restricted to owner read/write (0600). You can inspect the path with stophy view-config.

On this page