Use the Mo CLI

Install the qa CLI and mo-qa skill to run Mo 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.

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

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

Authenticate

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

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

Get started

Essential guidelines

Set up Mo

Integrations

Working with Mo

Install the CLI

Authenticate

Run with your coding agent

Start a session

Read and control a session

Export the report

Move files

Test a local build through a tunnel

Command reference

​Install the CLI

​Authenticate

​Run with your coding agent

​Start a session

​Read and control a session

​Export the report

​Move files

​Test a local build through a tunnel

​Command reference

Install the CLI

Authenticate

Run with your coding agent

Start a session

Read and control a session

Export the report

Move files

Test a local build through a tunnel

Command reference