CLI
CLI reference
Every agentiqa command, flag, environment variable, and exit code — generated from the typed CLI schema.
Agentiqa CLI — AI-powered testing for web apps.
Commands
| Command | Summary |
|---|---|
agentiqa explore | Test a web app with an AI agent |
agentiqa run | Execute saved test plans |
agentiqa login | Authenticate with Agentiqa (opens browser) |
agentiqa logout | Remove stored credentials |
agentiqa whoami | Show the current authenticated user |
explore
Test a web app with an AI agent.
agentiqa explore "<prompt>" [flags]
| Flag | Description |
|---|---|
--url <url> | Web URL to test. Optional when logged in with a single project — the CLI reuses that project's URL. |
--feature <text> | What was built, from the user's perspective. |
--hint <text> | A specific thing to test. (repeatable) |
--known-issue <text> | Something the agent should NOT report. (repeatable) |
--credential <name:secret> | A login credential to hand the agent. (repeatable) |
--dry-run | Check the engine and exit without running the agent. |
--no-artifacts | Don't save screenshots/video to the temp directory. |
--verbose | Show raw observations and actions. |
--auto-approve | Auto-approve scope and plan checkpoints (required for non-interactive runs). |
--json | Emit machine-readable JSON on stdout (schemaVersion 1). |
--format <text|json> | Explicit output format; overrides the AG_OUTPUT env var. |
run
Execute saved test plans.
agentiqa run --url <url> --plan <path.json> [flags]
| Flag | Description |
|---|---|
--url <url> | Target URL (required with --plan; deprecated with a service key). |
--plan <path> | Path to a test plan JSON (required without a service key). |
--plan-id <id> | Run a single saved plan by id (service-key mode). |
--label-ids <a,b,c> | Run every plan tagged with any of these labels (csv, service-key mode). |
--label-id <id> | Alias for --label-ids. (deprecated) |
--mode <sequential|parallel> | Execution order for the selected plans (default: sequential). |
--artifacts-dir <path> | Directory for run artifacts (default: a temp directory). |
--no-artifacts | Don't save video/frame artifacts. |
--share | Mint an opt-in PUBLIC, revocable share link for each cloud run (added to the JSON envelope as shareUrl per plan) so a reviewer can open the run without an Agentiqa login. Cloud runs only; a no-op with a warning otherwise. Equivalent to AG_SHARE=1. |
login
Authenticate with Agentiqa (opens browser).
agentiqa login [--no-browser]
| Flag | Description |
|---|---|
--no-browser | Don't open a browser — print the auth URL to visit instead. |
logout
Remove stored credentials.
agentiqa logout
No command-specific flags.
whoami
Show the current authenticated user.
agentiqa whoami
No command-specific flags.
Common flags
Accepted by every command.
| Flag | Description |
|---|---|
--engine <url> | Engine URL (default: auto-start in-process). When set, Playwright/Chromium and ffmpeg are not required locally — the remote engine drives the browser and CLI run artifacts download the engine-rendered video when available (a local ffmpeg render is only used as a fallback). Customer-facing usage authenticates via AGENTIQA_SERVICE_KEY alone (a short-lived engine credential is minted automatically). |
--help | Show this help and exit. |
--version | Print the CLI version and exit. |
Environment variables
| Variable | Description |
|---|---|
AGENTIQA_API_URL | Override the Agentiqa control-plane API (default: https://agentiqa.com). |
AGENTIQA_SERVICE_KEY | Service key for unattended runs (CI). Replaces interactive login and unlocks hosted engine access — no separate engine token required. |
AGENTIQA_ENGINE_TOKEN | Optional internal bearer override for hosted engine HTTP + WebSocket calls. Only needed for internal infra; customer-facing CI should rely on AGENTIQA_SERVICE_KEY instead. |
AG_OUTPUT | Set to "json" to enable JSON output mode globally (equivalent to --json). Use --format text to override. |
AG_SHARE | Set to a truthy value (anything other than 0/false/empty) to enable public share links for cloud runs (equivalent to --share). |
AGENTIQA_UPDATE_CHECK | Set to "0" to disable the "Update available" check (a cached, fire-and-forget npm dist-tags lookup; sends no user data). Also disabled by { "updateCheck": false } in ~/.agentiqa/config.json. |
Exit codes
| Code | Meaning |
|---|---|
0 | Success — all selected plans passed (or there was nothing to run). |
1 | Plan failure — plans executed, at least one failed. |
2 | Usage / configuration error (bad flags, not authenticated, a selector that matched no plans, or a project with no plans to run), OR a persistent account-state block (quota / org run-cap exhausted). Nothing ran — retrying cannot help. |
3 | Infra / runtime error (engine unreachable, auth/exchange failure, a no-verdict batch, or an unexpected internal error) — a correct, entitled invocation could not reach a verdict, so it is safe for CI to retry. |
JSON output
With --json or AG_OUTPUT=json:
- Every JSON document includes "schemaVersion": 1 at the top level.
- Success: { "ok": true, "schemaVersion": 1, ...commandFields }
- Failure: { "ok": false, "schemaVersion": 1, "error": { "code": "...", "message": "..." } }
- All log lines go to stderr; stdout contains exactly one JSON document.
- ANSI color is disabled when --json is active or stdout is not a TTY.