CLI overview

Run Agentiqa from the terminal with the agentiqa CLI — explore a URL or run saved test plans, locally or in CI.

The agentiqa CLI runs the same agent as the apps, headless. It has two testing commands — explore (agent-led discovery) and run (deterministic saved-plan execution) — plus login, logout, and whoami. See the generated CLI reference for every flag.

Install

The CLI ships on npm and needs Node.js 18+ (Node 20 recommended). There is nothing to install ahead of time — npx -y fetches it on first use:

npx -y agentiqa@latest whoami

On Ubuntu CI, the distro's default apt-get install nodejs can be too old — use actions/setup-node@v4 or NodeSource to get Node 20+.

explore vs run

agentiqa explore "<prompt>" — the agent explores a URL, proposes what to test, and reports findings. Great for ad-hoc QA.
```
npx -y agentiqa@latest explore "Find bugs on the signup page" --url https://example.com
```

agentiqa run — replays your saved test plans and returns deterministic pass/fail. This is the command you wire into CI.

# Run all plans in the service key's project on the cloud engine
AGENTIQA_SERVICE_KEY=sk_... npx -y agentiqa@latest run --engine https://engine.agentiqa.com

Where the engine runs

In-process (default). With no --engine, the CLI starts an execution engine locally: it downloads Chromium on first use and drives the browser on your machine. Good for local targets (including localhost).
Hosted (--engine <url>). Sends the run to Agentiqa's cloud engine — no Chromium on your machine. AGENTIQA_SERVICE_KEY alone authenticates; a short-lived engine credential is minted automatically.

Selecting which plans run

With a service key, agentiqa run operates on that key's project. With no selector it runs every non-deleted plan; narrow it with:

--plan-id tplan_… — run a single saved plan.
--label-ids a,b,c — run every plan tagged with any of those labels (comma-separated lbl_… ids, OR match).

--plan-id overrides --label-ids when both are given, and a selector that matches no plans is a configuration error (nonzero exit) — a run that tests nothing is never a pass.

Parallel vs sequential

--mode controls how the selected plans execute. Each plan always runs as an independent engine session with its own browser, so plans never share cookies or state — --mode only changes ordering and concurrency.

--mode sequential (default) — plans run one at a time. Run memory is threaded from each plan into the next, and a transient per-plan engine disconnect is retried on a fresh session, up to three attempts total.
--mode parallel — plans run through a bounded worker pool to shrink wall-clock time. By default, up to four plans run concurrently and remaining plans start as workers become available. Each plan gets the same engine-disconnect recovery as sequential mode: it is retried on a fresh session, up to three attempts total.

Parallel has one deliberate caveat:

No run-memory threading — a plan that consumes an earlier plan's saved run memory has no upstream memory in parallel and is reported as dependency-blocked. Run dependent chains sequentially.

Prefer sequential when plans depend on each other; prefer parallel for an independent regression suite where bounded concurrency shortens wall-clock time. Both modes apply the same per-plan engine-disconnect retry.

Authentication

Interactive use: agentiqa login (opens a browser). Unattended use (CI): set AGENTIQA_SERVICE_KEY to a project-scoped service key — see CLI Service Keys.

In CI

For running the CLI in GitHub Actions, prefer the GitHub Action; for the exit-code contract and JSON envelope you parse, see CI Integration.