CLI

Install and sign in

curl -fsSL https://app.simulithic.com/cli/install.sh | sh     # one line, no npm; needs Node 20 or newer
export PATH="$HOME/.simulithic/cli:$PATH"                         # the installer prints this line
simulithic signup --code <invite code>     # first time; afterwards: simulithic login
simulithic whoami             # who you are and which workspaces you can use
simulithic use ws_xxxxxx      # the default workspace for later commands
simulithic 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 ~/.simulithic. In CI, set SIMULITHIC_TOKEN instead, minted with simulithic 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

simulithic map https://app.yourproduct.com --upload
simulithic map http://localhost:3000 --upload --max-pages 60
simulithic map --app build/MyApp.app          # a native Mac app: the build is uploaded and mapped on a Simulithic Mac worker
simulithic map --app app-release.apk          # an Android app: uploaded and mapped on a Simulithic phone (release build, arm64)
simulithic map --app build/…/Release-iphonesimulator/App.app   # an iOS app: the simulator build, mapped on an iPhone simulator
JOURNEYS_PASSWORD=… simulithic 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

simulithic flows                                 # every flow set in the workspace, with what a restore would bring back
simulithic flows show https://app.yourproduct.com
simulithic flows upload journeys.json            # from an earlier map --no-upload
simulithic 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)
simulithic flows add app:com.yourproduct.app more.json   # add journeys by hand (same name = replaced); flows drop <origin> <name> takes one out
simulithic flows restore https://app.yourproduct.com   # undo the last upload; run again to swap back
simulithic 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

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

Running against localhost

The simulated people run on Simulithic’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
simulithic 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 Simulithic; 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

simulithic specs journeys.json --out .simulithic

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