percio test

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

Flag	Description	Default
`-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`
`--headless`	Run the browser in headless mode.	`false` (visible)
`--timeout <seconds>`	Overall test timeout.	no limit
`-o, --output <path>`	Write JSON results to disk.	none
`-v, --verbose`	Print 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.

Get started

Creating a test

Personas

Reading results

Agent (CLI & MCP)

Test history

Plans, billing & credits

Account

Troubleshooting

Synopsis

Options

Examples

What you see in the terminal

Interactive scenario mode

Local persona presets vs. cloud personas

Exit codes

What’s next

​Synopsis

​Options

​Examples

​What you see in the terminal

​Interactive scenario mode

​Local persona presets vs. cloud personas

​Exit codes

​What’s next

Synopsis

Options

Examples

What you see in the terminal

Interactive scenario mode

Local persona presets vs. cloud personas

Exit codes

What’s next