Add public docs for QA Wolf's local execution CLI

docs.json

@@ -368,6 +368,27 @@
                 ]
               }
             ]
+          },
+          {
+            "group": "@qawolf/cli",
+            "icon": "terminal",
+            "pages": [
+              {
+                "group": "API Reference",
+                "pages": [
+                  "qawolf/libraries/cli/api-reference/index",
+                  "qawolf/libraries/cli/api-reference/commands",
+                  "qawolf/libraries/cli/api-reference/configuration",
+                  "qawolf/libraries/cli/api-reference/environment-variables"
+                ]
+              },
+              {
+                "group": "Troubleshooting",
+                "pages": [
+                  "qawolf/libraries/cli/troubleshooting"
+                ]
+              }
+            ]
           }
         ]
       },
@@ -439,6 +460,18 @@
               "qawolf/Azure-DevOps-Boards-29c5b2a994fb81b09697f2f1e4f9fdf1",
               "qawolf/Integrate-with-webhooks-29c5b2a994fb818d9682eb32ff11feff"
             ]
+          },
+          {
+            "group": "Local execution",
+            "icon": "terminal",
+            "pages": [
+              "qawolf/local-execution/authenticate",
+              "qawolf/local-execution/run-flows-locally",
+              "qawolf/local-execution/pull-flows",
+              "qawolf/local-execution/install-dependencies",
+              "qawolf/local-execution/set-up-a-project",
+              "qawolf/local-execution/diagnose-problems"
+            ]
           }
         ]
       },

qawolf/libraries/cli/api-reference/commands.mdx

@@ -0,0 +1,148 @@
+---
+title: "Commands Reference"
+description: "Reference notes for every qawolf CLI command and flag."
+sidebarTitle: "Commands"
+---
+
+The qawolf CLI exposes five top-level commands. Each section below documents the command's purpose, accepted arguments, and flags.
+
+## `auth`
+
+Manages authentication with the QA Wolf platform. Credentials are read from the `QAWOLF_API_KEY` environment variable first, then from the system keychain, then from a config file fallback.
+
+### `auth login`
+
+Prompts for an API key, validates it against the platform, and stores it locally. Requires an interactive terminal — in non-interactive contexts, set `QAWOLF_API_KEY` directly.
+
+```bash
+qawolf auth login
+```
+
+### `auth logout`
+
+Removes stored credentials. Credentials set via the `QAWOLF_API_KEY` environment variable cannot be removed by this command.
+
+```bash
+qawolf auth logout
+```
+
+### `auth whoami`
+
+Displays the authenticated team name, ID, optional slug, and the credential source.
+
+```bash
+qawolf auth whoami
+```
+
+## `flows`
+
+Manages and runs QA Wolf flows.
+
+### `flows run [pattern]`
+
+Runs flows matching `[pattern]`, or every flow when omitted. The default pattern matches `**/*.flow.{ts,js}` in the current working directory and in `.qawolf/<env>/` subdirectories.
+
+```bash
+qawolf flows run
+qawolf flows run "flows/checkout/**"
+qawolf flows run checkout --env staging --headed
+```
+
+Options:
+
+- `--retries <n>` — number of retries for each failing flow. Default: `0`.
+- `--bail` — stop after the first failure. Default: `false`.
+- `--workers <n>` — parallel worker count. Default: `1`. Currently capped at `1`.
+- `--timeout <ms>` — per-flow timeout in milliseconds. Default: `30000`.
+- `--video <mode>` — `on`, `off`, or `retain-on-failure`. Default: `off`.
+- `--trace <mode>` — Playwright trace mode. `on`, `off`, or `retain-on-failure`. Default: `off`.
+- `--har <mode>` — HAR capture mode. `on`, `off`, or `retain-on-failure`. Default: `off`.
+- `--har-content <mode>` — `omit` or `full`. `full` includes response bodies and uses more memory. Default: `omit`.
+- `--output-dir <path>` — directory for artifacts. Default: `qawolf-output`.
+- `--headed` — show the browser window instead of running headless. Default: `false`.
+- `--env <env>` — environment ID. When set, missing flows are pulled before the run.
+
+Exit codes: `0` when all flows pass, `1` when one or more flows fail, `2` for invalid arguments or an unrecognized flow target. See [Exit codes](/qawolf/libraries/cli/api-reference/index#exit-codes).
+
+### `flows list [pattern]`
+
+Lists flows matching `[pattern]`. By default, lists local flows; with `--remote`, lists flows from the QA Wolf platform.
+
+```bash
+qawolf flows list
+qawolf flows list "flows/checkout/**"
+qawolf flows list --remote
+```
+
+Options:
+
+- `--remote` — list flows from the QA Wolf platform instead of the local project. Default: `false`.
+
+### `flows pull`
+
+Downloads an environment's flows into the local `.qawolf/<env>/` cache.
+
+```bash
+qawolf flows pull --env staging
+qawolf flows pull --env 4e9c... --out ./snapshot
+qawolf flows pull --env staging --yes
+```
+
+Options:
+
+- `--env <env>` — required. The environment ID to pull from.
+- `--out <path>` — destination directory. Defaults to `.qawolf/<env>/`.
+- `--yes` — overwrite locally-modified files without prompting. Default: `false`.
+
+## `install`
+
+Installs every runtime dependency the project's flows need. With a `[pattern]` argument, only the dependencies for the matching flows are installed.
+
+```bash
+qawolf install
+qawolf install "flows/checkout/**"
+```
+
+### `install browsers [pattern]`
+
+Installs the Playwright browsers used by the project's web flows.
+
+```bash
+qawolf install browsers
+qawolf install browsers "flows/web/**"
+```
+
+### `install android [pattern]`
+
+Installs Android system images, AVDs, and the Appium driver used by the project's Android flows. Requires `ANDROID_HOME` or `ANDROID_SDK_ROOT`.
+
+```bash
+qawolf install android
+qawolf install android "flows/mobile/**"
+```
+
+## `init`
+
+Scaffolds a QA Wolf project in the current directory. Creates `qawolf.config.ts`, an example flow at `src/flows/example.flow.ts`, and `.qawolf/.gitignore`. Adds the `@qawolf/flows` dependency and a `test:e2e` script to `package.json`.
+
+```bash
+qawolf init
+qawolf init --yes
+```
+
+Options:
+
+- `--yes` — overwrite existing files without prompting. Default: `false`.
+
+## `doctor`
+
+Diagnoses problems running flows locally. Checks the CLI version, Node.js version, Playwright installation, browser availability for web flows, and the Android SDK for Android flows.
+
+```bash
+qawolf doctor
+qawolf doctor --all
+```
+
+Options:
+
+- `--all` — run every platform check, including platforms the project does not use. Default: `false`.

qawolf/libraries/cli/api-reference/configuration.mdx

@@ -0,0 +1,31 @@
+---
+title: "Configuration Reference"
+description: "Reference notes for the qawolf.config.ts file."
+sidebarTitle: "Configuration"
+---
+
+The qawolf CLI reads a `qawolf.config.ts` file at the project root. `qawolf init` generates this file with the defaults shown below. Fields set on the command line override the config.
+
+```typescript
+export default {
+  outputDir: ".qawolf",
+  timeout: 60_000,
+  retries: 0,
+  video: "retain-on-failure",
+};
+```
+
+## Fields
+
+- `outputDir` — directory for run artifacts such as videos, traces, and HAR files. Overridden by `--output-dir`.
+- `timeout` — per-flow timeout in milliseconds. Overridden by `--timeout`.
+- `retries` — number of retries for each failing flow. Overridden by `--retries`.
+- `video` — video capture mode. One of `"on"`, `"off"`, or `"retain-on-failure"`. Overridden by `--video`.
+
+## Generated Project Layout
+
+`qawolf init` writes the following files alongside `qawolf.config.ts`:
+
+- `src/flows/example.flow.ts` — a minimal web flow used as a starting point.
+- `.qawolf/.gitignore` — ignores the contents of `.qawolf/` except for the file itself.
+- `package.json` — created or updated to include `"type": "module"`, the `@qawolf/flows` dependency, and a `"test:e2e": "qawolf flows run"` script.

qawolf/libraries/cli/api-reference/environment-variables.mdx

@@ -0,0 +1,41 @@
+---
+title: "Environment Variables"
+description: "Environment variables read by the qawolf CLI."
+sidebarTitle: "Environment Variables"
+---
+
+The qawolf CLI reads the following environment variables.
+
+## `QAWOLF_API_KEY`
+
+API key for the QA Wolf platform. Used by `flows pull`, `flows list --remote`, and `flows run --env`. Required for any command that talks to the platform. Takes precedence over credentials stored via `qawolf auth login`.
+
+## `QAWOLF_API_URL`
+
+Base URL for the QA Wolf platform API. Defaults to `https://app.qawolf.com`. Trailing slashes are stripped.
+
+## `ANDROID_HOME`
+
+Path to the Android SDK root. Required by `qawolf install android` and by Android flow execution. `ANDROID_SDK_ROOT` is accepted as a fallback.
+
+## `ANDROID_SDK_ROOT`
+
+Fallback path to the Android SDK root, used when `ANDROID_HOME` is not set.
+
+## CI Detection
+
+The CLI treats the following variables as a signal that it is running in CI and switches the default output format to JSON:
+
+- `CI`
+- `GITHUB_ACTIONS`
+- `GITLAB_CI`
+- `CIRCLECI`
+- `JENKINS_URL`
+- `BUILDKITE`
+
+## Agent Detection
+
+The CLI treats the following variables as a signal that it is running inside an agent and switches the default output format to agent mode:
+
+- `CLAUDE_CODE`
+- `CURSOR_SESSION_ID`

qawolf/libraries/cli/api-reference/index.mdx

@@ -0,0 +1,46 @@
+---
+title: "API Reference"
+description: "API landing page for the qawolf CLI."
+sidebarTitle: "API Reference"
+---
+
+Use this section for stable command descriptions, flags, configuration, environment variables, and exit codes.
+
+## Commands
+
+- [`qawolf auth`](/qawolf/libraries/cli/api-reference/commands#auth) — manage authentication.
+- [`qawolf flows`](/qawolf/libraries/cli/api-reference/commands#flows) — run, list, and pull flows.
+- [`qawolf install`](/qawolf/libraries/cli/api-reference/commands#install) — install runtime dependencies for the project.
+- [`qawolf init`](/qawolf/libraries/cli/api-reference/commands#init) — scaffold a project in the current directory.
+- [`qawolf doctor`](/qawolf/libraries/cli/api-reference/commands#doctor) — diagnose problems running flows locally.
+
+Example invocation:
+
+```bash
+qawolf auth login
+qawolf flows pull --env <env>
+qawolf flows run
+```
+
+## Global Options
+
+The following flags apply to every command:
+
+- `--verbose` — emits debug logs to stderr.
+- `--json` — formats output as JSON.
+- `--agent` — formats output for agent consumption.
+
+When a recognized CI environment is detected (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `JENKINS_URL`, `BUILDKITE`), output defaults to JSON. When a recognized agent environment is detected (`CLAUDE_CODE`, `CURSOR_SESSION_ID`), output defaults to agent mode.
+
+## Exit Codes
+
+Every qawolf CLI command exits with one of the codes below.
+
+| Code | Name | Meaning |
+| --- | --- | --- |
+| `0` | `success` | The command completed successfully. |
+| `1` | `testFailure` | One or more flows failed. |
+| `2` | `invalidArgs` | A Commander parse error, an unknown subcommand, or a bad flag value. |
+| `3` | `auth` | `QAWOLF_API_KEY` is missing or invalid. |
+| `4` | `network` | The QA Wolf API was unreachable, a download from storage failed, or a registry was unreachable. |
+| `5` | `config` | `qawolf.config.ts` is invalid, or a file collision occurred during `qawolf init`. |