CLI
Updated 2026-11-02
Availability
The headstream command isn't published to npm yet, so you can't install it today. Each command is a thin wrapper around one GET request to the REST API, so everything on this page also works with curl. The table below shows the matching endpoint.
Configure
The CLI reads two environment variables:
| Variable | Notes |
|---|---|
HEADSTREAM_API_KEY | Required. Create one under Organization |
HEADSTREAM_URL | Optional. Defaults to https://headstream.app |
Commands
Output is JSON. The exit code is 0 on success, 1 on an API error and 2 on a usage error.
| Command | Flags | Endpoint |
|---|---|---|
sites | /api/v1/sites | |
summary | --site, --from, --to | /api/v1/summary |
traffic | --site, --from, --to | /api/v1/traffic |
breakdown | --site, --dimension | /api/v1/breakdown |
customers | --site | /api/v1/customers |
goals | --site | /api/v1/goals |
dashboards | --site | /api/v1/dashboards |
explain | --site, --metric | /api/v1/explain |
data-quality | --site | /api/v1/data-quality |
change-log | --site | /api/v1/change-log |
export | --site, --cursor | /api/v1/export |
status | --site | /api/v1/status |
fix | --site | /api/v1/fixes/top |
fixes | --site | /api/v1/fixes |
experiments | --site | /api/v1/experiments |
uptime | --site | /api/v1/monitor |
heatmap | --site, --path, --device | /api/v1/heatmap |
revenue-breakdown | --site, --dimension | /api/v1/revenue/breakdown |
revenue | --site, --model, --from, --to | /api/v1/revenue |
--site is the project ID from headstream sites.
Examples
headstream sites
headstream summary --site SITE_ID --from 2026-10-01 --to 2026-10-31
headstream breakdown --site SITE_ID --dimension utm_campaign
headstream revenue --site SITE_ID --model first_touch
headstream revenue-breakdown --site SITE_ID --dimension landing_path
headstream explain --site SITE_ID --metric bounce_rate
The same revenue call with curl:
curl "https://headstream.app/api/v1/revenue?siteId=SITE_ID&model=first_touch" \
-H "Authorization: Bearer hsk_YOUR_KEY"
Limits
The CLI only reads. To create goals, dashboards or tests, use the API or MCP server.