Setup and doctor

npx agent-qa init creates an agent-qa project in the folder it runs in, and on a project that is already set up it offers what to repair or upgrade. npx agent-qa doctor checks the project and this machine. Each prints its options with --help:

>npx agent-qa init --help

FlagsCopy Anchor Link

init sets up the folder it runs in. It refuses the filesystem root and the home folder.

--llm writes one model entry:

A key can also be saved from the terminal with npx agent-qa auth set --config <entry> --type api-key. A subscription choice, claude-code or codex, also adds the subscription entry to plugins and declares @vostride/agent-qa-subscription-auth in package.json at agent-qa's exact version. For what a first run asks and does, see Quickstart.

Run it againCopy Anchor Link

Run npx agent-qa init in a folder that already has agent-qa.config.yaml, without --force, and it repairs or upgrades the project instead of creating one. It prints a short summary under This project: the agent-qa version, the model's status and the coding agents. In a terminal it then asks Which coding agents should agent-qa set up?, pre-checked with the agents its manifest lists, and one multi-select, What should init set up here?. Its rows, in menu order, are also the --setup names:

A row is pre-checked when running it would change something. --yes and a run without a terminal take the pre-checks.

--setup answers the menu instead: row names separated by commas, all or none. all and none cannot be combined with names.

• all runs every shown row, except a version move that can break the config and, with --no-browsers, browsers.
• none runs no row. It prints the summary and each row's state, runs validate and exits, which makes it a status read.

npx agent-qa init --setup skills,mcp
npx agent-qa init --setup none --json

--llm, --model and --base-url set the model on a re-run. These are refused with exit code 2:

• --setup on a folder that is not set up yet;
• --setup together with --force;
• --platform on a set-up folder, whose platforms are its config's targets;
• --model or --base-url without --llm;
• --setup browsers together with --no-browsers.

Validate always runs after the rows. A row left unselected that would change something is listed in the next steps as npx agent-qa init --setup <row>.

UpgradeCopy Anchor Link

npx agent-qa init --setup upgrade

The upgrade row rewrites package.json with agent-qa, the subscription plugin and the first-party plugins at the latest exact version, installs them, then hands the rest of the run over to the copy it just installed.

A move that crosses a breaking step, a minor bump in 0.x or a major from 1.0, is never pre-checked and never taken by all. It runs only when its row is named in --setup, and --setup all prints the row as skipped with the reason breaking: name it in --setup. For such a move init prints that the new version can change your config, and one line per step crossed that points a coding agent at its migration guide:

agent-qa <to> can change your config. To upgrade, point your coding agent at
https://vostride.com/docs/agent-qa/migrate/v<from>-to-v<to>

A patch move links its release notes on GitHub instead. doctor's Newer agent-qa row warns when a newer version is published, and for a breaking move its fix is the same guide lines.

Run through npx agent-qa@latest init, the running copy is already the latest, so the upgrade row is hidden and deps carries the move:

npx agent-qa@latest init --setup deps

See Migrate an older project.

JSON outputCopy Anchor Link

--json prints one JSON document on stdout on every exit, a refusal and an interruption included, and the step lines on stderr. It asks nothing.

A fresh web project with --no-browsers, trimmed to three files:

{
  "format": 1,
  "outcome": "done",
  "exitCode": 0,
  "steps": [
    { "name": "package-json", "outcome": "done" },
    { "name": "scaffold", "outcome": "done" },
    { "name": "install", "outcome": "done" },
    { "name": "chromium", "outcome": "skipped", "reason": "--no-browsers", "command": "npx agent-qa install-browsers --chromium" },
    { "name": "skills", "outcome": "done" },
    { "name": "validate", "outcome": "done" },
    { "name": "dashboard", "outcome": "skipped", "reason": "not interactive" }
  ],
  "files": [
    { "path": "package.json", "outcome": "created", "step": "package-json" },
    { "path": "agent-qa.config.yaml", "outcome": "created", "step": "scaffold" },
    { "path": ".mcp.json", "outcome": "created", "step": "skills" }
  ],
  "agents": ["claude-code", "codex"],
  "packageManager": "npm",
  "agentQa": { "version": "<version>", "via": "project" },
  "plugins": [{ "package": "@vostride/agent-qa-subscription-auth", "version": "<version>" }],
  "model": { "name": "claude-code", "provider": "anthropic-subscription", "status": "pending", "reason": "not signed in" },
  "nextSteps": [
    { "command": "npx agent-qa install-browsers --chromium", "description": "Install the browser the examples run in" },
    { "command": "npx agent-qa auth login --config claude-code", "description": "Sign in with your subscription" },
    { "command": "npx agent-qa run suites/examples.suite.yaml", "description": "Run the examples: one passes, one fails on the playground's deliberate bug (exit 1)" },
    { "command": "npx agent-qa dashboard", "description": "Open the dashboard" }
  ]
}

Exit codesCopy Anchor Link

init's exit code says how the run ended:

With --json, the document's exitCode equals the process exit code.

doctorCopy Anchor Link

npx agent-qa doctor

doctor prints one row per check, each with a status of PASS, WARN, FAIL or SKIP. Every WARN and FAIL row has a Fix: line under it, and a row the re-run menu can fix names npx agent-qa init --setup with that row. The rows, in the order doctor prints them:

1. Node.js
2. Config file
3. Legacy v1 memory data
4. Knowledge store
5. Embedder
6. Retrieval rung
7. Config validation
8. agent-qa versions
9. Skills, one row per coding agent set up, such as Skills (Claude Code)
10. MCP entry, one row per coding agent set up, such as MCP entry (Codex)
11. AGENTS.md block
12. Secrets file
13. Workspace files
14. Docker
15. Model
16. LLM credential
17. Subscription Auth
18. LLM connection
19. Playwright
20. Remote, one row per remote
21. Plugin, one row per plugins entry
22. Appium
23. Appium drivers
24. Android SDK
25. Xcode
26. Devices, or one Device row per device
27. Newer agent-qa
28. Test discovery
29. Validate

With no coding agent set up, the per-agent rows are one Coding agents row, skipped. doctor skips the local browser row when every web test runs on a remote, and the local mobile rows when every device is remote. --remote <name> shows only that remote among the remote rows.

--json prints one document instead: format (1), ok, which is false exactly when a row failed, and rows. Each row has its name, its status in lowercase (pass, warn, fail or skip), its message, and a fix only on a warn or fail row:

{
  "format": 1,
  "ok": false,
  "rows": [
    { "name": "Node.js", "status": "pass", "message": "<node version>" },
    { "name": "Playwright", "status": "fail", "message": "no Chromium for agent-qa's Playwright", "fix": "Run `npx agent-qa install-browsers --chromium`" }
  ]
}

doctor exits 3 when any row is FAIL and 0 otherwise, so warnings alone exit 0. An unknown --remote exits 2.

See Quickstart, Coding agents, CLI and Migrate an older project.