Skip to main content
The main command. Runs a full usability test — browser automation, persona evaluation, and a written report — against any URL, including localhost.

​
Synopsis

percio test --url <url> [options]
Run without --flow to start an interactive scenario conversation in your terminal. Pass --flow to skip the conversation and run directly.

​
Options

FlagDescriptionDefault
-u, --url <url>Target URL to test. Supports localhost and any valid URL.required
-f, --flow <task>Scenario for the persona to attempt. Omit to run the interactive conversation.none
-p, --persona <preset>Local persona preset: casual, professional, or power.casual
--persona-id <uuid>Cloud persona UUID (from percio personas list). Overrides --persona.none
--max-steps <number>Maximum steps before the agent stops.50
--viewport <WIDTHxHEIGHT>Browser viewport. Bounds: 320–3840 × 240–2160.1280x800
--headlessRun the browser in headless mode.false (visible)
--timeout <seconds>Overall test timeout.no limit
-o, --output <path>Write JSON results to disk.none
-v, --verbosePrint detailed step-by-step output to the terminal.false
-c, --config <path>Path to a .perciorc.json config file.auto

​
Examples

Interactive mode. No --flow — Percio helps you build the scenario in your terminal: 
percio test --url https://example.com
Direct mode. Scenario provided, skip the Q&A: 
percio test --url https://example.com --flow "Sign up for an account"
Cloud persona. Run the test through a persona you created in the web app: 
percio personas list   # get the UUID
percio test --url https://example.com \
  --flow "Buy a product" \
  --persona-id 123e4567-e89b-12d3-a456-426614174000
Testing localhost. Probably your most common use case in development: 
percio test --url http://localhost:3000 \
  --flow "Create an account and post your first comment"
Headless in CI with JSON output. Runs without a visible window and writes results to disk: 
percio test --url https://staging.example.com \
  --flow "Complete checkout with a test card" \
  --headless \
  --output results.json
Mobile viewport. 
percio test --url https://example.com \
  --flow "Find the nearest store" \
  --viewport 390x844

​
What you see in the terminal

By default, Percio prints phase-level progress: navigating, executing the flow, analyzing results. With -v / --verbose, every step is logged with the agent’s reasoning and action details. When the run finishes, Percio writes a markdown report to the current directory: 
percio-report-2026-04-21T17-42-32.md
The same report is also saved server-side and appears in your web app test history.

​
Interactive scenario mode

When you omit --flow, Percio starts a conversational scenario builder in your terminal: 
$ percio test --url https://example.com

What do you want to test?
> Sign up flow for a new user

Great. What kind of user are we simulating?
> Someone who's never used the product before

Anything specific you're worried about?
> The email confirmation step

Based on your answers, here's the scenario:
  "As a first-time visitor, sign up for a new account, confirm your
   email, and post your first comment."

Proceed? (y/n)
You can refine the scenario before confirming. When you say yes, the test runs.

​
Local persona presets vs. cloud personas

The --persona flag accepts a built-in preset for local testing without setting up cloud personas. The three presets are intentionally generic — for real reports you’ll want to use --persona-id with a persona tailored to your product. Local presets:
  • casual — the default; a moderately tech-savvy everyday user.
  • professional — a business user focused on efficiency.
  • power — an expert user who expects shortcuts and density.
--persona-id overrides --persona when both are given.

​
Exit codes

  • 0 — test completed and a report was produced.
  • 1 — error (invalid flags, auth failure, daemon issue, etc.).
A test that runs to completion but is low-quality (agent abandoned the flow) still exits 0 — the report itself tells you what happened.

​
What’s next