CLI

Install and sign in

curl -fsSL https://app.simulathic.com/cli/install.sh | sh     # one line, no npm; needs Node 20 or newer
export PATH="$HOME/.simulathic/cli:$PATH"                         # the installer prints this line
simulathic signup --code <invite code>     # first time; afterwards: simulathic login
simulathic whoami             # who you are and which workspaces you can use
simulathic use ws_xxxxxx      # the default workspace for later commands
simulathic workspace create "Checkout app" --surface web   # a new project in your workspace (web, mobile or desktop); --use makes it the default

login saves an API token for this machine under ~/.simulathic. In CI, set SIMULATHIC_TOKEN instead, minted with simulathic token --name github-ci: a separate token, printed once, that lasts 90 days. logout revokes the machine’s own token server-side and leaves CI tokens working.

Map a product

simulathic map https://app.yourproduct.com --upload
simulathic map http://localhost:3000 --upload --max-pages 60
simulathic map --app build/MyApp.app          # a native Mac app: the build is uploaded and mapped on a Simulathic Mac worker
simulathic map --app app-release.apk          # an Android app: uploaded and mapped on a Simulathic phone (release build, arm64)
simulathic map --app build/…/Release-iphonesimulator/App.app   # an iOS app: the simulator build, mapped on an iPhone simulator
JOURNEYS_PASSWORD=… simulathic map https://app.yourproduct.com --upload \
  --login-url https://app.yourproduct.com/login --user qa@yourproduct.com

The explorer runs on your machine in a real browser, so localhost, staging and VPN-only apps all work. It follows every same-origin link, presses every non-destructive control on each page, reads forms without submitting them, and writes what it found to journeys.json and a readable journeys.md. With --upload the journeys become your workspace’s flows for that origin. The explorer itself is fetched from your account the first time you run map; it is not a public package.

Flows

simulathic flows                                 # every flow set in the workspace, with what a restore would bring back
simulathic flows show https://app.yourproduct.com
simulathic flows upload journeys.json            # from an earlier map --no-upload
simulathic flows show app:com.yourproduct.app    # a native app's journeys, by bundle id or Android package (--json prints them as a check takes them)
simulathic flows add app:com.yourproduct.app more.json   # add journeys by hand (same name = replaced); flows drop <origin> <name> takes one out
simulathic flows restore https://app.yourproduct.com   # undo the last upload; run again to swap back
simulathic flows remove https://app.yourproduct.com

Every upload keeps the set it replaces, so a map that turned out worse than the one before is one command away from being undone. map:diff a.json b.json lists what changed between two maps: pages added or removed, controls that came, went or point elsewhere, journeys added or removed.

Run a simulation

simulathic qa --url https://staging.yourproduct.com --goal "add an item to the cart and check out"
simulathic qa --url https://app.yourproduct.com --all-flows --n 18       # every flow, on every device your visitors use
simulathic qa --port 3000 --goal "sign up and create a project" --n 10   # a local dev server, tunnelled for the run
simulathic qa:list
simulathic qa:status run_xxxxxxxx

Running against localhost

The simulated people run on Simulathic’s workers, so localhost means nothing to them. When the target is local, qa opens a temporary public tunnel from your machine, waits until it answers, hands the workers that URL, and closes the tunnel the moment the run ends, errors or is interrupted. The tunnel is made with a tool you install once; the CLI does not bundle it:

brew install cloudflared            # macOS. Linux and Windows builds: github.com/cloudflare/cloudflared/releases
simulathic qa --port 3000 --all-flows --n 12

cloudflared needs no Cloudflare account and costs nothing: it opens one of Cloudflare’s free quick tunnels, with a random hostname that exists only for the length of the run. ngrok works too when it is on your PATH and has your auth token (--provider ngrok to force it). Nothing about the tunnel is billed by Simulathic; a run against localhost costs the same as a run against a public URL.

Your product map applies to the tunnelled build: --all-flows sends people through the flows mapped for your product, whatever hostname the run happens to use. The same goes for preview and staging hosts.

Generated specs

simulathic specs journeys.json --out .simulathic

Writes Playwright specs from a map, one per journey, with a desktop and a phone project, a sign-in setup and helpers. Files only change when the map does: a new journey arrives as a new file, a gone one is removed, an unchanged one is left alone, so the specs follow your product instead of rotting. They are optional: a deterministic gate you can run in your own CI before a check, which does not need them; see Pull-request checks.

Environment variables