Stophy CLI | Stophy

Install

Install with npm. You need Node.js 20 or later.

npm install -g @stophy/cli

To install without Node.js, use the standalone binary:

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

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

npx -y @stophy/cli init --all logs you in, adds Stophy’s agent skills to your agents, and adds the Stophy MCP server, in one command.

Authenticate

stophy login --browser

The CLI prints a code and opens stophy.dev. Check that the page shows the same code, then approve it. On a server with no browser, open the printed link on any other device: the CLI logs in once you approve there. To use an API key instead, pass it to login or set it as an environment variable:

stophy login --api-key st_...
export STOPHY_API_KEY="st_..."

Each computer gets its own key. Google search, Google News, Google Maps search, Reddit search, YouTube search, YouTube video and YouTube transcript work without logging in. Log out and revoke this computer’s key:

stophy logout

Make a call

Name the source, then the command:

stophy youtube search "bun runtime"
stophy google maps search --query dentist --location Berlin
stophy reddit subreddit rust
stophy youtube transcript https://youtu.be/M4TufsFlv_o
stophy google ads advertisers nike
stophy meta ads search nike

To point at one thing, give its link or its id as the argument, like stophy youtube video M4TufsFlv_o, or use the matching option, like --videoUrl or --videoId. Send one, not both. Run stophy <source> --help to see what a source can do, and stophy <source> <command> --help for every option on one command. If you give a value an option does not accept, the CLI stops before it calls Stophy and lists which values work.

Read the output

By default, lists print one row per result with its title and link, and other results print as name: value lines. Add --json to get the data as JSON instead, with the credits used printed to stderr. --raw prints the full response, including its request id.

stophy reddit search "bun runtime" --json

Page through results

Commands for sites with numbered pages take --page. Commands for sites with their own cursor end their output with a cursor when there is more; pass it back to get the next page:

stophy google search "bun runtime" --page 2
stophy reddit search "bun runtime" --cursor "<cursor from the last output>"

Save the output

-o <path> writes the output to a file instead of stdout:

stophy youtube search "bun runtime" --json -o results.json

Handle errors and retries

A failed call exits non-zero and writes its message to stderr. When the API says to wait, the message ends with Retry after Ns. and the CLI does not retry for you:

if ! stophy reddit search "bun runtime" --json -o out.json 2>err.txt; then
  cat err.txt
  exit 1
fi

To retry on a rate limit from a script, parse the wait time out of that message, or call stophy status first to check your account is live before a batch of calls.

Check your account

stophy status
stophy usage
stophy logs --days 7

status shows your login and balance. usage shows your balance and all-time usage. logs shows your recent requests.

Commands

Command	What it does
`stophy init`	Log in, install the agent skills, and add the MCP server
`stophy login`	Log in with your browser or an API key
`stophy logout`	Log out and revoke this computer’s key
`stophy <source> <command>`	Get data, for example `stophy youtube search`
`stophy endpoints [word]`	List every command and its cost
`stophy status`	Show your login, balance, and CLI version
`stophy usage`	Show your balance and all-time usage
`stophy logs`	Show your recent requests
`stophy doctor`	Check your install, login, and connection
`stophy version`	Show the CLI version

​Install

​Authenticate

​Make a call

​Read the output

​Page through results

​Save the output

​Handle errors and retries

​Check your account

​Commands