# CLI

A command-line client for the API. One file, no dependencies beyond Python 3. It suits scripts, scheduled jobs, and agents that run somewhere they cannot open a browser.

```bash
curl -fsSL https://sputnikintelligence.com/cli -o sputnik && chmod +x sputnik
```

We serve it from the app, so the client you download always matches the API you are calling. There is no version to keep in step.

## Credentials

```bash
export PROD_API_URL="https://sputnikintelligence.com"
export PROD_API_TOKEN="your-key"
```

If those are not set, it reads `.env` from the current directory. Environment variables take priority.

A missing token exits with code 3 straight away and names the variable it wanted.

## Commands

```bash
./sputnik posts search "your company" --window week
./sputnik posts get <slug>
./sputnik posts transcript <slug>
./sputnik people search "jane smith"
./sputnik alerts list
./sputnik hits list --alert <slug>

./sputnik spec          # every command, as JSON
./sputnik --help
```

## Options

**`--all`** follows cursors and returns every page.

```bash
./sputnik posts search "your company" --window month --all
```

**`--fields`** keeps only the fields you name. Useful when an agent is reading the output and does not need the rest.

```bash
./sputnik posts search "your company" --all --fields slug,title,published_at
```

**`--dry-run`** is available on every write. It shows the request and stops.

## Output

**stdout is JSON.** Progress, warnings and retry messages go to stderr, so you can parse stdout directly.

**Exit codes:**

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `2` | Validation. A bad parameter or a bad cursor. |
| `3` | Auth. Missing, wrong or revoked credential. |
| `4` | Not found. |
| `5` | Rate limited, or no plan. |
| `1` | Anything else. |

## Retries

Writes retry on a 429 or a 5xx, with exponential backoff. On a 429 we wait for the time the server asks for. Each write carries an idempotency key, so a retry will not create a second row. A 422 is never retried.

## Composing

The output is JSON, so it works with `jq`.

```bash
# Publications that mentioned you this month, by frequency
./sputnik posts search "your company" --window month --all --fields source \
  | jq -r '.items[].source.name' | sort | uniq -c | sort -rn
```

## MCP or the CLI

If your agent supports MCP, use MCP. There is nothing to install and the tools come with their own descriptions. Use the CLI where MCP cannot reach: cron jobs, containers, shell scripts. See [MCP](/docs/mcp).