The CLI & running in CI

Run your requests, flows, and collections from a terminal or any CI pipeline with the apistash command-line tool — the same definitions you build in the browser.

Authentication

The CLI authenticates with a personal access token (PAT). Create one in the app under Account → Personal access tokens. The token (format apistash_pat_…) is shown only once at creation, so copy it then — you can't view it again afterward.

Log in once

The easiest path is to run apistash login and paste your token when prompted. It's saved to a config file (~/.config/apistash/config.json, falling back to ~/.apistash.json, written with 0600 permissions) so future commands just work without re-entering it. Run apistash logout to remove the stored token.

# save your token to the config file
apistash login

# confirm who you're authenticated as
apistash whoami

Or use an environment variable

Alternatively, set the APISTASH_TOKEN environment variable. The CLI sends it as Authorization: Bearer <token> on every request — ideal for CI, where you'd store the token as a secret and expose it to the job.

export APISTASH_TOKEN="apistash_pat_…"
apistash run <flow-id> --env <env-id>

Token precedence

When more than one source is present, the CLI resolves the token in this order:

1. The --token flag.
2. The APISTASH_TOKEN environment variable.
3. The saved config file.

apistash whoami prints the authenticated user and which of these sources the token came from, which is handy for debugging CI runs.

apistash run

The apistash run command executes a request, a flow, or a whole collection — together with an environment — from the command line. It runs every step and evaluates every assertion along the way.

# run a single flow against an environment
apistash run <flow-id> --env <env-id>

# run an entire collection
apistash run --collection <collection-id> --env <env-id>

# write a report to a file
apistash run <flow-id> --env <env-id> --report junit --out results.xml

Reports

A run emits a JUnit or HTML report summarizing every step and assertion, so results show up natively in CI dashboards and as readable artifacts.

Fits any CI

The CLI returns a non-zero exit code on assertion failure, so it slots into any pipeline without extra glue — a failed assertion fails the build.

# GitHub Actions step
- name: API tests
  run: apistash run <flow-id> --env <env-id> --report junit --out results.xml

For APIs that aren't reachable from your CI runner's network, pair the CLI with the local agent.