> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the Stophy CLI, log in with the matching code or an API key, call an endpoint, page through results, and handle errors from a script.

## Install

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

```bash theme={null}
npm install -g @stophy/cli
```

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

```bash theme={null}
# 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

Log in with your browser:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
stophy logout
```

## Make a call

Name the source, then the command:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.