## Documentation Index

Fetch the complete documentation index at: [/docs/llms.txt](/content/docs/llms.txt)

Use this file to discover all available pages before exploring further.

Install the `qa` CLI and `mo-qa` skill to run [Mo](/content/docs/mo/index/index.html) from your coding agent. We recommend this for interactive work in your project: the skill prepares the brief, follows the session, and exports the report. You can also use the commands below in scripts. Mo runs in the cloud, so your target must be reachable from its hosted browser or through a [tunnel](/content/docs/mo/tunneling/index.html).

## Install the CLI

The npm launcher requires Node.js 22.12 or later in the 22.x series, or Node.js 24 or later. Install the `qa` package and confirm the command is available:

```
npm install -g qa
qa --help
```

The npm package supports macOS ARM64/x64, Linux ARM64/x64, and Windows x64. Keep optional dependencies enabled; Linux musl also requires `libstdc++`. See the [installation reference](/content/docs/cli-reference/mo/overview#install/index.html). Or install the standalone `qa` binary without Node.js:

```
curl -fsSL https://cli.momentic.ai/qa | sh
```

The installer writes `qa` to `$HOME/.local/bin` on Linux and macOS, on x86_64 and arm64. Add that directory to your `PATH` if the shell cannot find `qa`. Run the installer again to update. Set `MO_VERSION` to pin a version, or `MO_INSTALL_DIR` for another directory. Releases before 0.18 named the command and installed file `mo`. For an older install or conflicting commands on your `PATH`, see [troubleshoot the install](/content/docs/cli-reference/mo/overview#troubleshoot-the-install/index.html).

The npm package is `qa`. `npx mo` runs a different project.

## Authenticate

Sign in with a Momentic account that has Mo access, then check which account and organization the CLI uses:

```
qa login
qa whoami
```

`qa login` opens a browser and saves an API key in `~/.momentic/auth.json`, which `momentic` and `momentic-mobile` also use. For CI or a non-interactive agent shell, set `MOMENTIC_API_KEY` from your secret store instead. Create the key in [API keys and team](/content/docs/account/api-keys-and-team/index.html). `MOMENTIC_API_KEY` overrides the saved key. Operational commands also accept `--api-key`; `login` does not. `qa whoami` validates the active key and reports its source, so check it before starting a session in another organization.

## Run with your coding agent

From your project root, install the skills and select the coding agents you use:

```
qa skills
```

The command installs `mo-qa` and the shared Momentic skills, then adds a pointer to the selected agents’ instructions files. Use `qa skills --yes` to install for detected agents without prompts, or `qa skills --target codex` to choose an agent explicitly. See the [skills reference](/content/docs/cli-reference/mo/commands/skills/index.html) for install locations. Open the project in your coding agent and run:

```
/mo-qa bug bash <scope>
```

Replace `<scope>` with the target URL, expected behavior, sign-in instructions, and prohibited actions. The agent uses `mo-qa` to prepare the brief, start and follow the session, and export the report. If your agent does not support slash commands, ask it to load the `mo-qa` skill and run that brief. See the [Mo quickstart](/content/docs/mo/quickstart#start-from-a-terminal/index.html) for a complete request. If you ask it to fix bugs, the skill also supports fixing and rechecking them.

## Start a session

Write the [brief](/content/docs/mo/brief/index.html) in `brief.md`. This example checks a storefront cart without placing an order:

brief.md

```
Target: https://preview.example.com/cart
Scope: Add a product, change its quantity, and remove it as a signed-out shopper.
Expected behavior: The item count and total update after each action and persist after refreshing the page.
Prohibited actions: Do not sign up, place an order, submit payment, or change account settings.
```

Start the session and keep both fields from the JSON response. This example uses [`jq`](https://jqlang.org/) to extract the session ID and app URL:

```
mo_session_json=$(qa start "$(cat brief.md)") &&
  mo_session_id=$(printf '%s' "$mo_session_json" | jq -er '.sessionId') &&
  printf '%s' "$mo_session_json" | jq -er '.webUrl'
```

Open `webUrl` to follow the live session in the app. Use `mo_session_id` in the commands below. Without `jq`, run `qa start "$(cat brief.md)"` and copy the `sessionId` from its output. `qa start` returns once the session exists; it does not wait for testing to finish. Continue after the command prints the app URL. If it fails, resolve the error before using the session commands below; check `qa whoami` for an authentication error or [`qa doctor`](/content/docs/cli-reference/mo/commands/doctor/index.html) for an installation or connectivity problem. For an authenticated flow, pass credentials as environment variables and name them in the brief. Single quotes keep the shell from expanding them locally:

```
qa start 'Test checkout on https://preview.example.com. Sign in with $QA_EMAIL and $QA_PASSWORD. Do not submit payment.' \
  --env-var QA_EMAIL --env-var QA_PASSWORD
```

Set `QA_EMAIL` and `QA_PASSWORD` in the invoking shell first. The command fails if either is missing. You can also load a dotenv file with `--env-file .env.qa`. To reuse credentials without supplying them from your shell, select a [workspace environment](/content/docs/mo/sessions#reuse-credentials-across-sessions/index.html). The start options change where and how the session runs:

| Option | Use |
| --- | --- |
| `--tunnel <tunnel-id>` | Route the session’s traffic through a local tunnel from `qa tunnel start`. |
| `--time-budget <minutes>` | Set the [session time budget](/content/docs/cli-reference/mo/commands/start#options/index.html). Omit for no time limit. |
| `--environment <name>` | Use a named workspace environment. Mo sees variable names, descriptions, and the literal `BASE_URL` starting URL. Values are available during execution. |
| `--env-file <path>` | Load variables from a dotenv-format file into the session environment. Repeatable. |
| `--env-var <name>` | Copy a variable from your current shell into the session environment. Repeatable. |
| `--interaction-speed <speed>` | Set browser pacing to `default` (default) or `human`. |
| `--max-concurrency <count>` | Cap concurrent sub-agents with a positive integer, up to the organization limit. |

## Read and control a session

Read the transcript and inspect the state and finding counts:

```
qa read "$mo_session_id" --from start
qa status "$mo_session_id"
```

`qa status` returns immediately. Add `--full` for the latest message and findings. Prefer `displayState` when deciding what to do next:

| `displayState` | Next action |
| --- | --- |
| `running` | Mo is working. Read the transcript or wait for output. |
| `waiting_on_agents` | Sub-agents are working. Keep waiting. |
| `needs_you` | Read Mo’s question, answer with `qa send`, then wait again. |
| `ready`, `sleeping` | Mo and its sub-agents are idle. Export the report and review coverage. |
| `failed_start` | Inspect the transcript and session in the app to resolve the startup failure. |
| `cancelled` | The session was stopped. Review any partial findings before deciding whether to resume. |

Wait for up to 30 seconds for new output, or use `qa wait` to wait until Mo and its sub-agents finish, stop, or need input:

```
qa read "$mo_session_id" --from latest --timeout 30s
qa wait "$mo_session_id" --json
```

`qa wait` has no timeout flag. It exits `0` when the session finishes, `2` when Mo needs input, and `4` when the session was stopped. A successful wait does not mean the application passed; check the report for bugs and blocked cases. Answer a question or change the scope with `qa send`:

```
qa send "Use the test customer account and do not modify shared cart data." \
  --session-id "$mo_session_id"
```

If Mo is working, `qa send` steers its active turn. Mo reads your message between tool calls while in-flight tool work continues. If Mo is idle, your message starts its next turn. Stop the root turn and all active sub-agent turns when you need to end the work:

```
qa stop "$mo_session_id" --subagents
```

Without `--subagents`, `qa stop` stops only the root turn. Archive the session when you no longer need it:

```
qa archive "$mo_session_id"
```

## Export the report

Once Mo is idle, export the findings and available bug recordings to a local directory:

```
qa report "$mo_session_id" --require-idle --output mo-report
```

`--require-idle` checks once. It exits with `Report not ready` and writes nothing while Mo or its sub-agents are working or Mo needs input. It does not wait. Omit the flag only when you want an in-progress snapshot. Read `report.json` first. Its `findings` entries point to `bugs.json`, `testCases.json`, `verdicts.json`, `triage.json`, and any categories the server adds. Its `artifacts` entries list downloaded recordings or download errors. See [session reports](/content/docs/mo/reports#export-the-report/index.html) for the fields. After a fix deploys to the same target, send a recheck request and export to a different directory:

```
qa send "The cart fixes are deployed. Rerun the reported reproductions and check the original acceptance criteria." \
  --session-id "$mo_session_id" &&
  qa wait "$mo_session_id" --json &&
  qa report "$mo_session_id" --require-idle --output mo-recheck
```

If the wait exits `2`, answer Mo’s question before exporting. Compare the new verdicts with the original report; exporting does not rerun tests.

## Move files

Use `qa upload` and `qa download` to move files between your local machine and Mo’s hosted sandbox. Both commands need a session, because the sandbox belongs to that session:

```
mo_remote_path=$(qa upload --session-id "$mo_session_id" ./release-plan.md) &&
  qa send "Use the release plan at $mo_remote_path to check the requested scope." \
  --session-id "$mo_session_id" &&
  qa download --session-id "$mo_session_id" "$mo_remote_path" --output ./release-plan-copy.md
```

`qa upload` prints the sandbox path. Give Mo that path, because a local path has no meaning inside the sandbox. `qa download` writes to `--output`, to `MOMENTIC_ARTIFACTS_DIR`, or to `.momentic-artifacts`.

## Test a local build through a tunnel

A tunnel lets Mo reach an app on your machine or private network. Start your app first, open a tunnel for the exact host and port in the brief, then pass the tunnel ID to `qa start`:

```
mo_tunnel_json=$(qa tunnel start localhost:3000) &&
  mo_tunnel_id=$(printf '%s' "$mo_tunnel_json" | jq -er '.tunnelId') &&
  qa start "Test the cart on http://localhost:3000/cart. Do not place an order or submit payment." \
  --tunnel "$mo_tunnel_id"
```

Keep the app and tunnel running until the session finishes, then run `qa tunnel stop "$mo_tunnel_id"`. Include other private addresses in `qa tunnel start` if the flow calls them. See [tunneling](/content/docs/mo/tunneling/index.html) for network requirements, current feature status, and the Connector option.

## Command reference

Every command has a detailed page with all options, output shapes, and examples in the [qa CLI reference](/content/docs/cli-reference/mo/overview/index.html).

| Command | Action |
| --- | --- |
| [`qa login`](/content/docs/cli-reference/mo/commands/login/index.html) | Sign in with a Momentic account and save an API key. |
| [`qa logout`](/content/docs/cli-reference/mo/commands/login#logout/index.html) | Sign out. |
| [`qa whoami`](/content/docs/cli-reference/mo/commands/login#whoami/index.html) | Show the account and organization for your API key. |
| [`qa doctor`](/content/docs/cli-reference/mo/commands/doctor/index.html) | Check installation, authentication, and connectivity. |
| [`qa skills`](/content/docs/cli-reference/mo/commands/skills/index.html) | Install the Momentic skills for your coding agents. |
| [`qa start <message>`](/content/docs/cli-reference/mo/commands/start/index.html) | Start a session from a brief. |
| [`qa send <message> --session-id <id>`](/content/docs/cli-reference/mo/commands/send/index.html) | Steer the active turn or start the next turn with a message. |
| [`qa read <session-id>`](/content/docs/cli-reference/mo/commands/read/index.html) | Print the session transcript. |
| [`qa wait <session-id>`](/content/docs/cli-reference/mo/commands/wait/index.html) | Wait for the session and sub-agents; report pending input. |
| [`qa status <session-id>`](/content/docs/cli-reference/mo/commands/status/index.html) | Return a session snapshot; `--full` adds the findings. |
| [`qa cost <session-id>`](/content/docs/cli-reference/mo/commands/cost/index.html) | Show the session’s recorded usage and cost. |
| [`qa report <session-id>`](/content/docs/cli-reference/mo/commands/report/index.html) | Export the report and bug recordings to a directory. |
| [`qa stop <session-id>`](/content/docs/cli-reference/mo/commands/stop/index.html) | Stop the active turn. |
| [`qa archive <session-id>`](/content/docs/cli-reference/mo/commands/archive/index.html) | Archive a session. |
| [`qa download <source> --session-id <id>`](/content/docs/cli-reference/mo/commands/download/index.html) | Move a file from the hosted sandbox to the local machine. |
| [`qa upload <source> [destination] --session-id <id>`](/content/docs/cli-reference/mo/commands/upload/index.html) | Move a file from the local machine to the hosted sandbox. |
| [`qa tunnel start <address...>`](/content/docs/cli-reference/mo/commands/tunnel#tunnel-start/index.html) | Start a tunnel for one or more addresses. |
| [`qa tunnel stop <tunnel-id>`](/content/docs/cli-reference/mo/commands/tunnel#tunnel-stop/index.html) | Stop a tunnel and revoke Mo’s access. |
| [`qa tunnel list`](/content/docs/cli-reference/mo/commands/tunnel#tunnel-list/index.html) | List tunnels started on this machine. |
| [`qa version`](/content/docs/cli-reference/mo/commands/version/index.html) | Print the installed version and check for updates. |
| [`qa upgrade [version]`](/content/docs/cli-reference/mo/commands/upgrade/index.html) | Replace the installed binary with the latest release. |
| [`qa licenses`](/content/docs/cli-reference/mo/commands/licenses/index.html) | Show the CLI licenses.