@synthers/cli

CLI for running Synthers AI UX simulations from the command line and CI pipelines. A thin client over the Synthers Public API - no browser, no AI, just HTTP.

Install

npm install -g @synthers/cli
# or run without installing
npx @synthers/cli run ...

Requires Node.js 20 or newer.

Authentication

Create an API key in your Synthers organisation settings, then either export it:

export SYNTHERS_API_KEY=sth_live_...

or pass --api-key to any command.

Usage

Run a simulation (CI gate)

synthers run \
  --url https://staging.myapp.com \
  --persona "First-time visitor, not tech-savvy" \
  --goal "Complete checkout as a new user" \
  --fail-on-risk-above 70

Creates a simulation, polls until it finishes (10s interval), prints the result, and exits with:

| Exit code | Meaning | | --------- | ----------------------------------------------------------------------------- | | 0 | Simulation analysed and risk score within threshold (or no threshold set) | | 1 | Simulation analysed but risk score above --fail-on-risk-above | | 2 | Simulation broke (failed/stopped/system_error), timed out, or API/usage error |

Simulations that end as abandoned (persona gave up), max_steps_reached (step cap hit), or needs_manual_input (persona asked its operator for input) still produce a full risk report, so they gate on the risk threshold exactly like completed ones. The report can land shortly after the status turns terminal, so the CLI keeps polling up to 90 extra seconds for it.

Flags:

• --project <id> - project to attach the simulation to. When omitted, the CLI matches the target URL's domain against your projects and fails with a list if nothing matches.
• --device <desktop|tablet|mobile> - viewport preset (API default: desktop)
• --location <EU|US> - worker location (API default: EU)
• --max-steps <n> - maximum navigation steps, 1-30 (API default: 30)
• --pre-context <text> - free-text background and requirements given to the persona before the run
• --question <text> - question the persona answers during the run (repeatable)
• --post-question <text> - question the persona answers after the run (repeatable); answers appear in every output format
• --test-login-email <email> - email the persona types into the target app's login form
• --test-login-password <password> - password for --test-login-email (default: SYNTHERS_TEST_LOGIN_PASSWORD env var)
• --branch <name>, --commit-hash <sha>, --build-number <id>, --release-version <tag> - CI metadata recorded on the simulation so Synthers can track when findings first appear
• --fail-on-risk-above <score> - exit 1 if the completed simulation's risk score exceeds this value (no threshold by default)
• --timeout <seconds> - how long to wait for completion (default: 900)
• --webhook-url <url> - URL the API calls when the simulation finishes
• --webhook-secret <secret> - secret used to sign the webhook payload (default: SYNTHERS_WEBHOOK_SECRET env var); requires --webhook-url
• --no-wait - start the simulation, print its ID, and exit 0 immediately
• --output <human|json|github> - output format (default: human)

--output github prints a GitHub-flavoured markdown report (Executive Summary, Experience Quality with risk/goal/mood/clarity, Findings Summary, and Findings with dashboard links) and, when $GITHUB_STEP_SUMMARY is set, appends it to the job summary automatically.

The result includes the project's findings observed in this run. Each finding carries isNewFinding (first seen in this run), the severity assessed in this run, and an editUrl linking to the finding in the Synthers dashboard.

Test feature-specific requirements

Feed a feature's requirements into the simulation with --pre-context, and probe them directly with questions:

synthers run \
  --url https://staging.myapp.com \
  --persona "New customer" \
  --goal "Buy a plan using promo code SAVE20" \
  --pre-context "Promo codes were just added at checkout. Requirements: field is visible before payment, invalid codes show an inline error, price updates after applying." \
  --question "Did you notice the promo code field without searching for it?" \
  --post-question "Was the discounted price clearly confirmed before payment?" \
  --post-question "What was the most confusing step?"

Post-simulation answers are printed in the result (and in the GitHub job summary with --output github).

Progress messages go to stderr, so --output json pipes cleanly:

synthers run ... --output json | jq .riskScore

Authenticated flows

Most staging environments sit behind a login. Give the persona test credentials and it logs in through the app's login form before pursuing its goal:

export SYNTHERS_TEST_LOGIN_PASSWORD=...   # keeps the password out of shell history and CI logs

synthers run \
  --url https://staging.myapp.com \
  --persona "Returning customer" \
  --goal "Change the subscription plan" \
  --test-login-email [email protected]

The password resolves from SYNTHERS_TEST_LOGIN_PASSWORD when --test-login-password is not passed. Passing only half of the pair is a usage error (exit 2), but an exported password alone is ignored, so a globally set variable does not affect unauthenticated runs. The password never appears in the CLI's output.

In GitHub Actions, map the password from a repository secret:

- name: UX gate
  run: |
    synthers run \
      --url https://staging.myapp.com \
      --persona "Returning customer" \
      --goal "Change the subscription plan" \
      --test-login-email [email protected] \
      --fail-on-risk-above 70
  env:
    SYNTHERS_API_KEY: ${{ secrets.SYNTHERS_API_KEY }}
    SYNTHERS_TEST_LOGIN_PASSWORD: ${{ secrets.SYNTHERS_TEST_LOGIN_PASSWORD }}

Note this is a form login: the persona types the credentials into your app's own login page, like a real user. It is not HTTP basic auth or header injection, so a staging site behind basic auth or an IP allowlist needs those lifted for the simulation's worker separately.

Webhooks

Instead of keeping the CLI alive to poll, pass a webhook URL and let the API notify you when the simulation finishes. Combined with --no-wait this is the recommended CI pattern - fire and forget:

export SYNTHERS_WEBHOOK_SECRET=whsec_...   # keeps the secret out of shell history and CI logs

synthers run \
  --url https://staging.myapp.com \
  --persona "First-time visitor" \
  --goal "Complete checkout as a new user" \
  --webhook-url https://ci.myapp.com/hooks/synthers \
  --no-wait

The secret signs the webhook payload so your receiver can verify it came from Synthers. It resolves from SYNTHERS_WEBHOOK_SECRET when --webhook-secret is not passed, and is only sent when a webhook URL is set.

Other commands

synthers get <id>                # fetch a simulation (human, json, or github output)
synthers list                    # list recent simulations (--limit, --offset, --project)
synthers stop <id>               # stop a running simulation (already-ended counts as stopped)
synthers projects list           # list projects
synthers projects create --name "Marketing site" --url https://example.com

Environment variables

| Variable | Purpose | | ------------------------------ | ------------------------------------------------------------------------ | | SYNTHERS_API_KEY | API key used when --api-key is not passed | | SYNTHERS_WEBHOOK_SECRET | Webhook signing secret used when --webhook-secret is not passed | | SYNTHERS_TEST_LOGIN_PASSWORD | Test-login password used when --test-login-password is not passed | | SYNTHERS_BASE_URL | Override the API base URL (default: https://synthers.ai/api/public/v1) |

Development

npm install
npm run typecheck        # tsc --noEmit
npm test                 # vitest
npm run test:cov         # tests with coverage summary (100% enforced)
npm run lint             # oxlint
npm run format           # oxfmt, writes in place
npm run format:check     # oxfmt, check only
npm run build            # bundles to dist/ via tsup
node dist/cli.js --help

A husky pre-commit hook runs format:check, lint, typecheck, and test:cov, so commits fail on formatting drift, lint warnings, type errors, or coverage below 100%.

Releasing

Publishing to npm happens in GitHub Actions when a version tag is pushed:

npm version patch        # bumps package.json, commits, and tags vX.Y.Z
git push --follow-tags

The workflow re-runs all checks, verifies the tag matches package.json, and publishes using the NPM_TOKEN repository secret (an npm granular access token with publish rights to the @synthers scope).