@percio/cli

Run Percio usability tests from your terminal — including sites on localhost.

Percio is an AI-assisted usability testing product: you describe a scenario and a persona, and Percio explores your product like a real user would, then surfaces UX insights.

The CLI is for developers and automation: same account as the web app, runs in your environment, and fits into scripts or CI when you want structured output.

What you need

• Node.js 18 or newer
• A Percio account and an API key — create the account at percio.app; the key lives under account settings (Integrations / API).
• Chromium for local browser runs (install once):

npx playwright install chromium

Install

Run without installing globally:

npx @percio/cli --help

Or install globally:

npm install -g @percio/cli
percio --help

Configure

API key — pick one:

1. Saved login (recommended for daily use):

 percio login

Paste your API key when prompted. It is stored in a small local config file. 2. Environment variable (common in CI):

 export PERCIO_API_KEY=your_api_key_here

If both are set, the environment variable wins.

Quick start

List personas from your workspace:

percio personas

Run a test (replace the persona id with one from the list):

percio run-test --url http://localhost:3000 --persona-id <persona-id>

The CLI will guide you through the scenario when you don’t pass --scenario.

JSON output (for scripts or CI):

percio --format json run-test --url https://example.com --persona-id <persona-id> --scenario "Complete onboarding as a first-time user"

Use at least about 20 characters in --scenario so the goal is clear.

Commands

| Command | Purpose | | ----------------- | ------------------------------------------------------------------------------ | | percio login | Save your API key (and optional base URL) locally. | | percio personas | List personas available in your account. | | percio run-test | Run a usability test on --url with --persona-id and optional --scenario. | | percio scrape | Fetch structured content from a public --url via Percio. | | percio results | List recent results, or percio results <id> for one result. | | percio --help | Help for the program and subcommands. |

Global flag: put **--format json** before the subcommand for machine-readable output.

Also available: MCP

To use Percio from an AI assistant (Cursor, Claude Desktop, etc.), see [@percio/mcp](https://www.npmjs.com/package/@percio/mcp).

License

© Percio