---
title: "Setup and doctor"
description: "agent-qa init and doctor reference: every init flag, the re-run menu and its --setup rows, upgrades, init's JSON document, exit codes, and each doctor row."
canonical_url: "https://vostride.com/docs/agent-qa/setup"
md_url: "https://vostride.com/docs/agent-qa/setup.md"
last_updated: "2026-11-12T09:37:25+05:30"
---

> [Documentation index](https://vostride.com/docs.md) · [Site index](https://vostride.com/llms.txt)
> Follow the Markdown links to read individual pages; the indexes list the available documentation.

# Setup and doctor

> agent-qa init and doctor reference: every init flag, the re-run menu and its --setup rows, upgrades, init's JSON document, exit codes, and each doctor row.

`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`:

```bash
npx agent-qa init --help
```

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

| Option | Meaning |
| --- | --- |
| `--platform <list>` | Platforms to test: `web`, `android` and `ios`, separated by commas, for example `web,android`. |
| `--llm <choice>` | The model: `claude-code`, `codex`, `anthropic`, `openai`, `gemini`, `openai-compatible`, `anthropic-compatible`, or the name of a saved credential. Default a saved sign-in, else `claude-code`. |
| `--model <id>` | The model id. Default the provider's default model. |
| `--base-url <url>` | The endpoint for `anthropic`, `openai`, `openai-compatible` or `anthropic-compatible`. A compatible endpoint takes `--model` and `--base-url` together. |
| `--agents <list>` | Coding agents to set up: `claude-code`, `codex`, `all` or `none`. Default the ones detected, or both when none is. |
| `--no-browsers` | Do not download Chromium for web targets. |
| `--no-dashboard` | Do not start the dashboard at the end. |
| `--force` | Overwrite existing files. |
| `--setup <list>` | On a set-up project, the rows to set up: row names separated by commas, `all` or `none`. See [Run it again](https://vostride.com/docs/agent-qa/setup.md#run-it-again). |
| `--pm <name>` | The package manager to install with: `npm`, `pnpm`, `yarn`, `bun`, or `none`, which writes `package.json` and installs nothing. Default detected from the project. |
| `--yes` | Ask nothing and take every default. |
| `--json` | Print one JSON document on stdout and the steps on stderr. Asks nothing. See [JSON output](https://vostride.com/docs/agent-qa/setup.md#json-output). |
| `--capabilities` | Print the JSON capability manifest and exit. Writes nothing. |

`--llm` writes one model entry:

| `--llm` | Entry it writes | Default model | Left after init |
| --- | --- | --- | --- |
| `claude-code` | `claude-code` | `claude-sonnet-5-5` | `npx agent-qa auth login --config claude-code` |
| `codex` | `codex` | `gpt-6.1-sol` | `npx agent-qa auth login --config codex` |
| `anthropic` | `anthropic` | `claude-sonnet-4-6` | Add the key on the dashboard's model page. |
| `openai` | `openai` | `gpt-5.5` | Add the key on the dashboard's model page. |
| `gemini` | `gemini` | `gemini-3-flash-preview` | Add the key on the dashboard's model page. |
| `openai-compatible` | `openai-compatible`, only when `--model` and `--base-url` are both given | None: `--model` names it | Without both flags, set it up on the dashboard's model page. |
| `anthropic-compatible` | `anthropic-compatible`, only when `--model` and `--base-url` are both given | None: `--model` names it | Without both flags, set it up on the dashboard's model page. |

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](https://vostride.com/docs/agent-qa/quickstart.md).

## Run it again
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:

| Row | What it does |
| --- | --- |
| `upgrade` | Upgrades agent-qa. Shown only when a newer version is published. |
| `deps` | Installs agent-qa's missing packages. |
| `skills` | Sets up the coding agents. |
| `mcp` | Restores the coding agents' MCP entries. |
| `agents-md` | Restores agent-qa's block in `AGENTS.md` and the knowledge guide. |
| `browsers` | Installs Chromium for agent-qa's Playwright. |
| `gitignore` | Restores init's `.gitignore` block. |
| `scaffold` | Writes a missing file the config points at. |

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.

```bash
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>`.

## Upgrade
```bash
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:

```text
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:

```bash
npx agent-qa@latest init --setup deps
```

See [Migrate an older project](https://vostride.com/docs/agent-qa/migrate/v0-2-to-v0-3.md).

## JSON output
`--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.

| Key | Value |
| --- | --- |
| `format` | `1`. |
| `outcome` | `done`, `failed`, `refused` or `interrupted`. |
| `exitCode` | The process exit code. See [Exit codes](https://vostride.com/docs/agent-qa/setup.md#exit-codes). |
| `message` | Only on a refusal, an interruption or an unexpected error: one line saying what happened. |
| `steps` | Each step with its `name` and `outcome`: `done`, `skipped` or `failed`. A skipped or failed step adds its `reason`, and the `command` that runs it when it has one. |
| `files` | Each file the run wrote, kept or removed, with its `path` relative to the folder, its `outcome` (`created`, `updated`, `kept`, `replaced` or `removed`) and its `step`. |
| `agents` | The coding agents set up: `claude-code`, `codex`, both or neither. |
| `packageManager` | Only once init knows it: `npm`, `pnpm`, `yarn`, `bun` or `none`. |
| `agentQa` | Only when a step ran agent-qa: its `version`, and `via`, which is `in-process`, `project` or `running`. |
| `latest` | Re-run only. Where the latest version came from, `registry`, `cache` or `none`, and its `version`. |
| `upgrade` | Re-run only, when a version move is offered or done: `from`, `to`, `breaking`, `links` and `row`, which is `upgrade` or `deps`. |
| `plugins` | The plugins init declared, each with its `package` and `version`. |
| `model` | Only once a model is chosen: its `name`, `provider` and `status`, `ready` or `pending`, with a `reason` while it is pending. |
| `setup` | Re-run only. Each menu row with its `name`, `state`, `prechecked` and `selected`, and `hidden` with the reason a row is not shown. |
| `nextSteps` | What is left to do, each with its `command` and `description`. |

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

```json
{
  "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 codes
init's exit code says how the run ended:

| Code | Meaning |
| --- | --- |
| `0` | Done. |
| `3` | A step failed. |
| `2` | Refused: a bad flag or flag value, an unusable folder, or a malformed managed file. |
| `130` | Interrupted. |
| `1` | An unexpected error. |

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

## doctor
```bash
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:

```json
{
  "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](https://vostride.com/docs/agent-qa/quickstart.md), [Coding agents](https://vostride.com/docs/agent-qa/coding-agents.md), [CLI](https://vostride.com/docs/agent-qa/cli.md) and [Migrate an older project](https://vostride.com/docs/agent-qa/migrate/v0-2-to-v0-3.md).

## Documentation navigation

- [All documentation](https://vostride.com/docs.md)
- Parent: [What is agent-qa](https://vostride.com/docs/agent-qa.md)
- Previous: [CLI](https://vostride.com/docs/agent-qa/cli.md)
- Next: [MCP server](https://vostride.com/docs/agent-qa/mcp.md)