CLI overview

The agentiqa CLI runs the same agent as the apps, headless. It has two sides:

• Explore & author — agentiqa explore proposes what to test, and the plan verbs (plan list / get / save) plus runs get let you and your coding agent curate, save, and read back test plans. This is the interactive agent-authoring loop. agentiqa project list shows which projects those verbs can work in — see Choosing a project.
• Run & gate — agentiqa run replays saved plans and returns deterministic pass/fail. This is the command you wire into CI.

Plus login, logout, and whoami. See the generated CLI reference for every command and 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. It also returns a draft plan you can curate and save (see the authoring loop). 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. With a service key it runs on the hosted engine by default — no --engine flag needed:

  # Run all plans in the service key's project (hosted engine, by default)
  AGENTIQA_SERVICE_KEY=sk_... npx -y agentiqa@latest run

To save, read, and revise plans by id from your coding agent — the full explore → review → save → run → read loop — see Agent skill.

Where the engine runs

agentiqa run picks its engine automatically, and you can override it:

• Hosted (default with a service key). An authenticated agentiqa run (AGENTIQA_SERVICE_KEY set) now defaults to Agentiqa's env-matched cloud engine (engine.agentiqa.com) — so CI needs no --engine. No Chromium on your machine, and the run persists to your account (run link, server-side video). The service key alone authenticates; a short-lived engine credential is minted automatically.
• Embedded / in-process (--embedded). Forces an execution engine inside the CLI process instead: it downloads Chromium on first use and drives the browser on your machine, so it can reach local targets (including localhost) and run offline. Embedded runs execute locally and do not persist to your account (no run link or server-side video).
• Explicit (--engine <url>). Pins a specific engine URL; overrides the default and --embedded.

To test a localhost target, use --embedded (or point --engine at a reachable engine).

Choosing a project

plan, runs, and labels operate inside one project. agentiqa project list shows every project the logged-in account can reach — the ones it owns and the ones a teammate shared with its organization — with an explicit access marker:

npx -y agentiqa@latest project list

ID                NAME     TARGET URL                 ACCESS
proj_7q1x8k2m0    web      https://app.example.com    owner
proj_mr26brft0    asklio   https://asklio.example     shared · org

Then pick one, once, per machine:

npx -y agentiqa@latest project use asklio     # by id or by unique name
npx -y agentiqa@latest project current        # what the next command will use

The project is resolved in this order, first match winning:

1. --project <id|name> on the command.
2. AGENTIQA_PROJECT_ID in the environment.
3. The project remembered by agentiqa project use.
4. The only project the account can access, when there is exactly one.
5. On an interactive terminal, a prompt that lists the projects and remembers your choice. In CI (or with --json, or piped stdin) there is no prompt — the command fails immediately with the list of options, so a job never hangs.

AGENTIQA_SERVICE_KEY overrides all of the above: a service key is scoped to one project by construction. Only a project's owner can mint a service key — but you do not need one: a logged-in member can run a shared project directly with project use / --project / AGENTIQA_PROJECT_ID.

A shared project's saved plans are readable, and a plan with a sign-in step resolves its credential by name: your own credential is used when you have one stored under that name in Project Settings → Project credentials, and otherwise a free shared account of that name, provisioned for the team by an admin. A personal credential's secret stays yours — nobody else can see it. When neither exists, the run is refused before it starts, naming the credential to add. See Team projects.

Selecting which plans run

agentiqa run operates on the project resolved above — the service key's project when one is set, otherwise the project you picked. With no selector it runs every non-deleted plan; narrow it with:

• --plan-id tp_… — 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:

1. 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). That is enough for every command — run included, against a project's saved plans — with no service key; see Choosing a project for how the project is picked. You may run any project you can reach: your own, and any project shared with your organization.

Unattended use (CI): set AGENTIQA_SERVICE_KEY to a project-scoped service key — see CLI Service Keys. A service key needs no browser and no interactive step, which is what makes it the right credential for an unattended job; it also overrides the project selection, since it is scoped to one project by construction.

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.