Skip to main content
Momentic supports local and remote iOS simulators. Real devices are not supported. Local simulators need macOS; remote simulators run from any host.

​
Set up with AI

Using a coding agent? Copy this prompt and paste it into Claude Code, Cursor, Codex, Copilot, or any other agent. It runs the wizard with an API key, because an agent cannot complete the browser sign-in, then writes your first test.

​
Prerequisites

The wizard and the manual setup both need:
  • Node.js 22.12.0+ or 24.0.0+ (node -v)
  • A package.json in your project. Run npm init -y if you do not have one. Commit it with the lockfile, so CI and local runs use the same Momentic version.
  • A Momentic account. Sign up to create one.
The manual setup also needs a build of your app. See iOS app setup. Local simulators also need macOS, Xcode, Xcode Command Line Tools, and idb. The wizard uses a remote simulator, so its sample run needs no local Xcode or app build.

​
Set up with the wizard

Run the wizard in your terminal:
It signs you in through the browser, installs momentic-mobile, writes momentic.config.yaml and a sample test under ios/, runs the sample test on a remote simulator, and asks which coding agents to set up.

​
Manual setup

1

Install

The examples below use npx. With pnpm, use pnpm exec momentic-mobile; with yarn, use yarn momentic-mobile.
2

Authenticate

Sign in with your browser:
The CLI saves the credentials to ~/.momentic/auth.json and uses them when MOMENTIC_API_KEY is not set.In CI, or in a shell without a browser, use an API key instead. Create one in the dashboard and export it:
Check which account and organization the CLI uses:
3

Initialize

This writes momentic.config.yaml to your project root. In an interactive terminal, it also offers to install the coding agent skills and the MCP server. init --yes accepts the defaults without prompts, so it works in agent shells and CI.init does not create tests. You write your first one in the editor below. For a sample test, use the wizard above instead.
4

Connect your coding agent (optional)

Skip this step if init already did it. The two commands are independent: skills are local instruction files, the MCP server is a live process that gives the agent a device and Momentic tools.
Both commands detect the coding agents on your machine and ask which ones to configure. Pass --yes to skip the prompt. See Building with AI for what each one does.
5

Build your app

Momentic installs a simulator .app bundle. Build it with the tab that matches your stack. See iOS app setup for full instructions.
In Xcode, select Product, then Build For, then Testing. This produces a .app bundle that Momentic can install on a simulator.
6

Upload your build (remote simulators)

Momentic manages remote simulators, so you do not need local Xcode after you upload your build:
Local simulators also work, but they boot slower. See iOS simulators for the LOCAL_IOS_DEVICE_TYPE and LOCAL_IOS_APP_PATH setup.
7

Write and run your first test

Open the local editor:
You write mobile tests in this local editor, not in the web app. The dashboard at app.momentic.ai shows results. A browser-based editor for mobile tests is not available yet.
Create a test, select the dev channel and the 1.0.0 tag, and write one natural-language step, for example Tap the Sign in button. Save the test. The editor writes the .test.yaml file to your project. Run it from the editor, then run it from the CLI by name:
--upload-results sends the result to the dashboard. Without it, the run stays on your machine.
8

Verify

  • Check that the .test.yaml file exists in your project.
  • Open the dashboard and check Runs for the result.

​
Next steps

iOS app setup

Xcode build, .app bundling, required signing

Simulators

Local vs. remote simulators and device types

Building with AI

Skills, the MCP server, and a prompt for your coding agent

CI/CD

Run mobile tests on every pull request
Clone momentic-ai/examples for a full working example.