Command-line client

A command-line client for the API. One file, no dependencies, installable in a container that has nothing but curl and Python 3.

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

It is served by the app itself rather than released separately, so the client you download always matches the API you are calling. There is no version to keep in step.

Credentials

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

If they are not exported it reads .env from the working directory, which is where they already live when you are sitting in a repo. The environment always wins.

A missing token exits 3 immediately, naming the variable it wanted — rather than firing the request and handing you a bare 401 to work backwards from.

Using it

./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, machine-readable
./sputnik --help

Built for agents

stdout is JSON and nothing else. Progress, retries and warnings all go to stderr. One stray human-readable line on stdout breaks every caller parsing the output, so there are none.

Exit codes mean something, so a script can branch and a schedule can fail loudly:

Code	Means
0	Success.
2	Validation — a bad parameter, a bad cursor.
3	Auth — missing, wrong or revoked credential.
4	Not found.
5	Rate limited, or no plan.
1	Everything else.

--all follows cursors. Paging is the tool's job, done once and correctly, instead of being a procedure a caller re-derives every time.

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

--fields trims the payload. A hundred full rows is a lot of an agent's context spent on fields the job does not read.

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

--dry-run is on every write. It shows the request it would send and stops.

Writes retry properly — honouring Retry-After, backing off with jitter, and carrying an idempotency key so a retry cannot double-post. It retries a 429 or a 5xx and never a 422: repeating a request the server rejected on its merits only burns your allowance.

Composing

It writes JSON, so it composes with jq like anything else:

# Every publication 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