CLI reference

From npx stresseur --help, version 0.4.0. Installed in a project, stress is the same command.

record

Start the local recorder. Binds 127.0.0.1 only.

npx stresseur record [options] [-- <command that starts your app>]
  --app <url>       Serve your app at localhost:3738 with the recorder added (no SDK)
  --app-port <n>    Port for --app (default 3738, a free one when busy; 0: a free one)
  --port <n>        Collector port (default 3737, a free one when busy; 0: free ports for both)
  --browser <url>   Like --app, then open it in your browser
  --dir <path>      Project to record into (env STRESSEUR_DIR)
  --json            JSON lines on stdout, for tools; a "done" line on stdin stops recording
  --stop-on-stdin-eof  With --json: stop when stdin closes

--app and --browser also record page loads and form posts, under your app’s address.

generate

Turn recorded sessions into YAML flows.

npx stresseur generate [options]
  --out <dir>       Output directory (default api-tests)
  --name <name>     Flow and file name
  --session <id>    One recorded session
  --all             One file per distinct pattern (at most 10)
  --no-load         Omit the starter load: smoke block
  --har <file>      Build flows from a browser HAR file
  --origin <url>    With --har: your app's address, if the HAR's first page is elsewhere
  --verify <url>    Verify against this server instead of APP_URL
  --no-verify       Don't run the new flows
  --strict          Exit 1 when a verified step fails
  --dir <path>      Project to read (env STRESSEUR_DIR)
  --upload          Also send the flow files to your workspace
  --no-upload       Never send the flow files
  --json            One JSON line on stdout, for tools

Flow files are sent only with --upload or a yes in that run. Being logged in never sends them.

--har sets APP_URL as the base URL, maps variables and adds stream: to streamed responses. On an AI endpoint, generate prints a hint to add expect: checks. See Record flows and AI checks.

sessions, graph

npx stresseur sessions [--json] [--dir <path>]   List recorded sessions
npx stresseur graph [--json] [--dir <path>]      Recorded API map (.stresseur/graph.html)

init

Records your app, generates the tests, runs them twice and offers CI and a pull request (see Quickstart):

npx stresseur init [options]
  --url <url>          Your app's address (default: detected)
  --start "<command>"  The command that starts your app (default: its dev script)
  --dir <path>         The app's directory, e.g. in a monorepo
  --demo               Record a built-in sample shop, no app needed; with --yes,
                       --json or no terminal it checks out by itself
  --yes, -y            Answer yes to every question
  --no-ci              Don't offer the CI check
  --no-pr              Don't offer the pull request
  --json               JSON events on stdout; a "done" line on stdin ends the recording
  --stop-on-stdin-eof  With --json: stdin closing also ends it
  --sdk                Print the SDK install snippet

Exit code 0 when the tests pass, 1 when one fails, 2 for bad options.

npx stresseur demo [--port <n>] [--json]   Serve the sample shop init --demo records (default port 4599)

demo runs until Ctrl-C (with --json, until a done line on stdin), so the tests init --demo wrote can run again.

install-skill

npx stresseur install-skill [options]
  --agent <claude|codex|cursor|all>   Default all
  --dir <path>      Claude skill directory (default .claude/skills/stresseur)
  --force           Overwrite a hand-written file

Writes .claude/skills/stresseur/SKILL.md, a section in AGENTS.md, and .cursor/rules/stresseur.mdc. The skill runs npx stresseur init, fixes failing steps, adds expect: checks to AI endpoints, and offers a HAR file when the recorder can’t be used.

init-ci

npx stresseur init-ci [options]
  --out <path>      Workflow file (default .github/workflows/stresseur.yml)
  --tests <dir>     Flow directory (default api-tests)
  --target <mode>   compose, docker, start or url (default: detected)
                    compose, docker and start always start the app in CI, even if APP_URL is set
  --force           Overwrite a workflow this command didn't write, or write one with no flows yet

init-ci won’t write a workflow while the flow directory is empty (--force overrides). It warns when your flows call a separate API, and lists what your app needs in CI: a database, and variables left empty in .env.example.

ci

Run every flow several times and report per step. Exits 1 if any step failed.

npx stresseur ci [<file.yamlflow.yaml>...] [options]
  --tests <dir>         Default api-tests
  --iterations <n>      Measured runs per flow (default 12)
  --warmup <n>          Warm-up runs per flow (default 1)
  --out <path>          Report (default .stresseur/ci-report.json)
  --capture <what>      none (default) or failed: keep failed steps' request and response, masked
  --target-mode <mode>  compose, docker, start, url or preview
  --report stresseur    Upload the report afterwards

upload

npx stresseur upload [<report.json>] [--strict]

Credentials, first found: GitHub Actions OIDC, STRESSEUR_TOKEN, the login token. --strict exits 1 when the upload fails.

login, logout, whoami, pr-opened

npx stresseur login [--force] [--no-browser]   Link this computer to a workspace
npx stresseur logout                           Revoke and delete the saved token
npx stresseur whoami                           Show the linked workspace
npx stresseur pr-opened <pull request URL>     Show the PR on the onboarding page

flow run

Run a flow, or a load test from the file’s load: block.

npx stresseur flow run [yamlflow-file] [flow-name] [flags]
  --scenario <name>         Run a load: entry as a load test
  --vus <n>                 Virtual users (with --duration and/or --iterations)
  --duration <d>            How long to start new iterations, e.g. 60s
  --iterations <n>          Total iterations across all virtual users
  --load-file <path>        Extra load scenarios
  --vus-scale <f>           Multiply VU counts (default 1)
  --rate-scale <f>          Multiply arrival rates (default 1)
  --frame-interval <d>      Metrics frame cadence (default 5s)
  --report <format[:path]>  console (default), json, junit, frames:<url>
  --show-output             Print each step's output
  -q, --quiet               Less output
  --config <path>           Default $HOME/.devtools.yaml

Reads ./.env.stresseur.local (where init writes when git tracks .env), then ./.env, then the .env next to the flow file; variables set in the shell win. It stops before running when a {{ #env:NAME }} the flow uses is not set, and names each one.

Exit codes: 0 done, 99 threshold failed, 108 aborted, 1 could not run.

Environment variables

Variable	Used by
APP_URL	Your app’s address, for flows and generate verification. Read from the shell, then .env. STRESSEUR_BASE_URL, its name before 0.4, still works; APP_URL wins if both are set
STRESSEUR_JUDGE_API_KEY	The key for AI-check judges. ANTHROPIC_API_KEY and OPENAI_API_KEY also work. An empty value counts as unset
STRESSEUR_DIR	record, generate, sessions, graph
STRESSEUR_TOKEN	upload, whoami
STRESSEUR_API_URL	Server (default https://app.stresseur.com)
STRESSEUR_REPOSITORY	ci outside GitHub Actions (owner/name)