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:
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:
<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:
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. Runnpx -y qa login, then add npx -y qa mcp as the
momentic-hosted stdio server:
Claude Code
Codex
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:- Discover available configuration, then start the session.
- Read progress, pending questions, and a bounded report summary. Open its
webUrlto review or share the full report. Hosted tools do not export a report directory. - Send Mo your answers. After deploying a fix, ask your agent to recheck the original finding. It retests only when you ask.
- 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.
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
jq to extract the session ID and app URL:
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:
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:
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:
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:
--subagents, qa stop stops only the root turn. Archive the session
when you no longer need it:
Export the report
Review findings withqa 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:
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:
2, answer Mo’s question before exporting. Compare the new
verdicts with the original report; exporting does not rerun tests.
Move files
Useqa 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.
--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:
./app.apk with the simulator .app directory. Run Android
and iOS as separate sessions. Check that the build is ready without starting a
session:
--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 withqa start through a
tunnel, then collect findings with qa wait and qa report.
Start a session over HTTP
KeepMOMENTIC_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:
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 returnedsessionId. Poll
GET /v1/mo/sessions/:sessionId/status every 10 seconds with the same API key:
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:
GET /v1/mo/sessions/:sessionId/report. A cancelled
session’s report keeps what Mo recorded before it stopped:
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.