Skip to main content
Drive Mo from a coding agent or a terminal with the qa CLI, and from scripts and CI with the CLI or the HTTP API. Mo runs in the cloud, so a localhost or private web target goes through a tunnel. Follow Install the qa CLI, then sign in with qa login. On Windows Server 2016, use the compatibility package.

Run with your coding agent

mo-qa is the coding-agent Mo skill. It keeps the interface you request. Otherwise, it uses hosted tools with an existing Connector for private web targets, or the CLI for a new tunnel. Hosted sessions reach private targets through an online Connector. If none is online, the agent asks you to run npx -y qa tunnel start --name <name> <address> on a machine that reaches the target and waits; it doesn’t run sign-in or tunnel commands itself. A blocked hosted session reports the blocker without switching interfaces. From your project root, install the skill and select the coding agents you use:
The command installs only mo-qa and adds a pointer block for it to the selected agents’ instructions files. Use qa skills --yes to install for detected agents without prompts, or qa skills --target codex to pick an agent. See the skills reference for install locations. Open the project in your coding agent and run:
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. For example:
Replace both localhost:3000 addresses with your app’s address. Answer questions about access, expected behavior, and boundaries before the agent continues. If you ask it to fix bugs, the skill also supports fixing and rechecking them. qa skills doesn’t write MCP config. You can skip its hosted MCP setup suggestion when you want the CLI only. For Cursor Agent’s config and approval commands, see MCP setup.

Hosted MCP for coding agents

With the Momentic plugin, use its bundled hosted OAuth connection. To opt into the CLI bridge, disable the plugin’s hosted entry first. For CLI bridge setup, connect the hosted Momentic MCP with a saved CLI sign-in. Run npx -y qa login, then add npx -y qa mcp as the momentic-hosted stdio server:
Claude Code
Codex
Claude.ai and ChatGPT connectors keep https://mcp.momentic.ai with OAuth. The hosted MCP and CLI support different operations: The mo-qa skill covers both. When you ask for hosted tools, it keeps them and reports hosted authentication failures rather than switching to the CLI.

Use the hosted MCP tools

Ask your agent to use the hosted MCP tools with your brief:
  1. Discover available configuration, then start the session.
  2. Read progress, pending questions, and a bounded report summary. Open its webUrl to review or share the full report. Hosted tools do not export a report directory.
  3. Send Mo your answers. After deploying a fix, ask your agent to recheck the original finding. It retests only when you ask.
  4. Once testing is complete, read the finished report and summarize findings and uncovered requirements. It stops the session only when you ask or agree, and reports its actual result; an idle session may have nothing to stop.
See the hosted MCP tool reference for exact tool names.

Start a session

For an uploaded mobile build, add --platform, --channel, and --tag; see qa start for accepted values. Write the brief in brief.md. This example checks a storefront cart without placing an order:
brief.md
Start the session and keep both fields from the JSON response. This example uses jq to extract the session ID and app URL:
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: For an authenticated flow, pass credentials as environment variables and name them in the brief. Single quotes keep the shell from expanding them locally:
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. qa environments list --search staging prints environment names and public BASE_URL values, without secret values. To give a running session credentials, save them from your shell with qa secrets set, then tell Mo their names:
The start options change where and how the session runs:

Read and control a session

Read the transcript and inspect the state and finding counts:
qa status returns immediately. Add --full for the latest message and the list of bugs. Use status when deciding what to do next: For interactive progress, read new output in bounded 45-second waits. For CI and scripts that need a final outcome, use blocking qa wait:
qa wait follows Mo and its sub-agents. It allows five continuous minutes of checking or incomplete sleeping for work to resume. Check the report for bugs and blockers. See qa wait for options and output. Answer a question or change the scope with qa send:
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:
Without --subagents, qa stop stops only the root turn. Archive the session when you no longer need it:

Export the report

Review findings with qa bugs list <session-id>. Use qa bugs accept, fix, reopen, dismiss, or review to update their lifecycle; see triage for arguments and legacy command compatibility. Once Mo is idle, export the findings and available bug recordings to a local directory:
If Mo or its sub-agents are still working, Mo needs input, or Mo stopped, failed, or ended with an unknown outcome, qa report still exports but warns that the report may be partial. Read report.json first. Its findings entries point to bugs.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. Once testing is complete, export the report, then run qa stop "$mo_session_id" --subagents even if export fails. Summarize the findings and uncovered scope after stopping. After a fix deploys to the same target, send a recheck request and export to a different directory:
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:
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.

Manage mobile app builds

Upload an Android APK or iOS simulator .app directory before starting a mobile session. qa assets upload packages .app directories, checks the upload, and prints JSON with the resolved tag. You don’t need a Momentic project config.
Omit --tag on upload to generate an immutable tag. Re-uploading the same tag and checksum skips the byte transfer. A different build needs a new tag. An alias moves after the upload succeeds. Use --tag latest when downloading to select the newest build. Deleting a tag also removes aliases pointing to it. Upload, list, and delete print JSON. Download prints the local path. List accepts --channel, --tag (tag or alias), --platform, and --build-target filters. Download and delete require --platform, --channel, and --tag. Their build target defaults to universal for Android or simulator for iOS. Mo sessions use simulator builds. qa assets manages workspace app builds. Use qa upload --session-id for test fixtures on a session’s machine.

Run a mobile bug bash

Mobile sessions need Mo mobile access in your workspace. Use an Android APK or iOS simulator .app from your app’s build instructions or CI. The hosted device must be able to reach the app’s test backend. Upload the build and keep its resolved tag. These shell examples use jq:
For iOS, replace ./app.apk with the simulator .app directory. Run Android and iOS as separate sessions. Check that the build is ready without starting a session:
Describe the app, goal, test account, allowed data and prohibited actions in the brief. Choose testing effort, then start with the returned build selection:
For authenticated flows, add --environment <name> or use the credential options, including qa secrets set when Mo asks for an account mid-session. Keep passwords out of the brief and messages. Browser authentication-state files don’t sign in a native app. Follow the session and answer its questions. Give credentials with qa secrets set, not in messages. After testing and reproductions finish, check coverage and export the report, then run qa stop "$mo_session_id" --subagents, even if export fails. Keep the build tag and session link with the findings, evidence and uncovered scope. Leave uploaded builds in place unless you intend to delete them. To recheck a fixed binary, upload a new immutable tag and start a new mobile session with the original reproduction requirements. qa bugs fix records a fix; it doesn’t install the new binary or verify it. To test a web app on localhost or a private network, see tunneling.

Run Mo from CI

Start Mo after your deployment is ready and export the findings for your script or CI job to review. Use a Momentic API key to authenticate. For a local or private target, start the session with qa start through a tunnel, then collect findings with qa wait and qa report.

Start a session over HTTP

Keep MOMENTIC_API_KEY in your CI secret store. This request starts a web session and returns sessionId and webUrl:

Start a PR session from CI

Send the provider and PR reference to /v1/mo/pr-sessions. GitHub is the supported PR provider. previewUrl is optional; supply it when your script or coding agent knows which deployment to test:
Without previewUrl, Mo discovers the preview from the PR, and the request fails if it finds none. A saved environment supplies configuration, not a replacement for the required preview target. Both start endpoints accept an optional top-level slackChannel, such as "C0123ABC" or "#checkout-qa", to deliver reports and requests for input to that channel. Connect the Momentic Slack app and invite it to the channel first. An unknown channel or missing bot membership rejects the start before a session is created. With the CLI, pass --slack-channel '#checkout-qa' to qa start.

Wait and fetch the report

For either start route, keep the returned sessionId. Poll GET /v1/mo/sessions/:sessionId/status every 10 seconds with the same API key:
Read canonicalDisplayState, falling back to displayState. Keep polling while it’s running, waiting_on_agents, or checking. On needs_you, the loop exits non-zero so the job doesn’t treat a question as a finished session; open webUrl and answer it. A failed request or a failed_start or failed session also exits non-zero:
When the loop ends, fetch GET /v1/mo/sessions/:sessionId/report. A cancelled session’s report keeps what Mo recorded before it stopped:
For other idle or stopped states, inspect reason and nextAction; the report may be partial. Review the report’s findings, verdicts, and coverage gaps before deciding whether the app met your criteria. A settled session is not proof that the app passed. For recurring testing, configure a Mo schedule with a prompt and environment. Each scheduled run starts a new session. Copy its session ID from the schedule’s past-run link or session URL, then use the HTTP recipe above. Every command is in the qa CLI reference.