> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecustory.com/llms.txt > Use this file to discover all available pages before exploring further. # Run Experiences from the CLI > Save a customer scenario, run it on desktop or mobile, review its report, and handle human confirmations from the same Experience records as the app. 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: ```bash theme={null} npm install --global @custory/cli@latest custory experience --help ``` Use [Authentication and workspaces](https://docs.usecustory.com/cli/authentication.md) 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](https://docs.usecustory.com/billing-and-usage.md), 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: ```bash theme={null} custory experience create --workspace "Acme" ``` 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: ```bash theme={null} custory tools describe custory.prepare_experience --json ``` 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: ```bash theme={null} custory experience list --workspace "Acme" custory experience show SCENARIO_ID --workspace "Acme" custory experience update SCENARIO_ID --workspace "Acme" ``` 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: ```bash theme={null} custory experience create --from SCENARIO_ID --name "Pricing page comparison" --workspace "Acme" ``` 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: ```bash theme={null} custory experience run SCENARIO_ID --workspace "Acme" --device desktop ``` 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: ```bash theme={null} custory experience status RUN_ID --workspace "Acme" --watch ``` Closing the terminal, pressing Ctrl-C, or reaching a local wait timeout leaves the remote run running. To request cancellation explicitly: ```bash theme={null} custory experience cancel RUN_ID --workspace "Acme" ``` 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: ```bash theme={null} custory experience status RUN_ID --workspace "Acme" custory experience approve RUN_ID --approval APPROVAL_ID --workspace "Acme" ``` 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: ```bash theme={null} custory experience history --workspace "Acme" --scenario SCENARIO_ID custory experience report RUN_ID --workspace "Acme" ``` 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: ```bash theme={null} custory experience report RUN_ID --workspace "Acme" --format markdown > experience-report.md ``` 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: ```bash theme={null} custory experience create --resume --workspace "Acme" custory experience run SCENARIO_ID --resume --workspace "Acme" ``` 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. ## Related updates * [Customer Experience from your terminal](https://usecustory.com/changelog/customer-experience-cli) * [A journey from the terminal](https://usecustory.com/changelog/a-journey-from-the-terminal) ## Next step Review the report and its linked journey in the [journey editor](https://docs.usecustory.com/journey-editor.md), or connect a coding agent through [MCP](https://docs.usecustory.com/cli/agents-and-mcp.md) to work from the same customer context. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.