Skip to main content
Use the Custory CLI to test a customer goal on your website and review where a synthetic customer session encountered friction. The scenario, versions, runs, reports, and linked journeys are the same records you see in the app and through MCP.

​
What an Experience is

An Experience describes a customer, a goal, a starting URL, and what successful completion looks like. A scenario is that saved setup. A run is one attempt to carry it out. For example, test whether a founder comparing SaaS plans can find the right plan and understand its price. You can save that setup, run it after a pricing-page change, and compare the reports without writing the instructions again. Treat findings as evidence from a synthetic session. Check the report’s observations and limitations before deciding what to change for real customers.

​
Before you start

You need Node.js 22.12 or newer, a signed-in Custory account, and edit access to the workspace to create or run an Experience. Viewers can read scenarios and reports. Install or update the CLI:
Use Authentication and workspaces if you need to sign in. Experience commands first shipped in CLI 0.10.0; the copy command below uses the 0.11.0 workflow. If commands or tools are missing, update the CLI and check custory tools list. Experience runs use the workspace credit balance, with a free first report for eligible users. Preparing a scenario also uses AI assistance. Saving a scenario does not itself start a browser run.

​
Create and review a scenario

Start with the interactive flow:
Describe the customer, goal, starting website, and observable success condition. Choose browse, signup, or existing-account login access, then a device. Review the prepared setup and assumptions before saving. You can describe the customer and goal in text or use saved persona and goal references through JSON input. For scripts, use --file ./scenario.json or --stdin. Inspect the current input contract before preparing a file:
Saving and running are separate operations. Add --run when you deliberately want creation to launch the saved scenario too.

​
Find, update, or copy saved setup

List scenarios, then inspect one using its returned ID:
Replace SCENARIO_ID and RUN_ID in these examples with IDs returned by Custory. Changing execution settings creates a new version, so earlier runs keep the setup they used. Name and description edits do not rewrite those versions. To use an existing scenario as a starting point:
Copying preserves the saved setup and creates a new scenario. It copies neither run history nor credentials. Use --from-version VERSION_ID with --from to copy a specific saved version.

​
Run on desktop or mobile

After you confirm that you are authorized to test the website, start a run:
The interactive command asks for website authorization. In a script, pass --confirm-target-authorization only after a person has confirmed it. Use --device mobile for a mobile browser or --device both for desktop and mobile. These are browser sessions, not native mobile-app tests. Running both creates separate runs with independent outcomes and reports. Existing-account login supports one device at a time. The command returns run IDs without waiting for completion. Add --wait to wait, or observe an existing run:
Closing the terminal, pressing Ctrl-C, or reaching a local wait timeout leaves the remote run running. To request cancellation explicitly:
Add --group to cancel both devices in the same run group. Cancellation is a request; check status again for the final state and cleanup.

​
Keep human confirmations separate

Website authorization confirms that the site may be tested. Approval of a specific consequential action is a separate decision. Neither can be supplied by --yes. If a run pauses for approval, read its current status and review the exact action before deciding:
Use the current approval ID from status. The interactive command asks you to confirm that action. Use deny instead of approve to reject it. Scripts require --confirm-action after that specific human decision. For existing-account login, use the protected credential handoff offered by the CLI. MCP callers receive an app link for the person to enter credentials. Keep passwords out of scenario JSON, ordinary tool arguments, and chat.

​
Review history and reports

Find earlier runs for a scenario and read a run’s findings:
History includes active, failed, and canceled runs as well as completed ones. Filter with --device desktop, --device mobile, or --status. Use --limit and the returned --cursor to read more pages. Check the goal outcome, findings, limitations, and any linked journey. A completed run does not by itself mean the customer goal passed. A pending or unavailable report has no score; that is different from a score of zero. Export the same Markdown report available in the app:
Use --json for structured output, or --full --json for detailed report data. Do not combine --json with --format markdown.

​
Recover an interrupted request

Use --resume with the same workspace and operation to recover its saved request:
Resume reuses the original request instead of intentionally starting another run. Use a fresh run command without --resume only when you want another attempt.

​
What good looks like

You have a narrow customer goal, clear success criteria, and a report you can trace back to the saved version and device. Turn one observed friction point into a specific improvement, then rerun the scenario to check what changed.

​
Next step

Review the report and its linked journey in the journey editor, or connect a coding agent through MCP to work from the same customer context.