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

​
Install via the wizard

Run the onboarding wizard in your terminal. It signs you in through the browser, then gets you to a passing iOS test in about two minutes: install, sample test run against a remote simulator, and editor MCP setup, all in one flow. 
npx @momentic/wizard@latest

​
Have a coding agent set it up

A coding agent can’t complete the browser sign-in, so the agent path uses an API key and runs the wizard non-interactively. Copy the prompt below into Cursor, Claude, or another agent:

Set up Momentic for an iOS project end to end via the onboarding wizard, non-interactively.

Open in Cursor
Or, to install manually, continue with the rest of this guide.

​
1. Prerequisites

  • Node.js 22.12.0+ or 24.0.0+
  • A build of your app (see iOS app setup)
  • For local simulators only: macOS, Xcode, Xcode Command Line Tools, and idb
  • A Momentic account, sign up to generate an API key
node -v  # need 22.12.0+ or 24.0.0+

​
2. Install

npm install --save-dev momentic-mobile

​
3. Authenticate

Option A: sign in with your browser (recommended): 
npx @momentic/wizard login
This opens a browser-based login flow and saves credentials to ~/.momentic/auth.json. Both CLIs automatically use this file when MOMENTIC_API_KEY is not set. Option B: use an API key: Create an API key in the dashboard, then export it: 
export MOMENTIC_API_KEY=your-api-key-here

​
4. Initialize

npx momentic-mobile init
This writes momentic.config.yaml to your project root. init does not scaffold any tests; author your first one in the editor below. (For pre-scaffolded sample tests, use the onboarding wizard instead.)

​
5. Build your app

Momentic installs a Simulator .app bundle. Build it with the tab that matches your stack. Full instructions are in iOS app setup; for more cross-platform detail see Cross-platform frameworks.
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)

Remote simulators are managed by Momentic, no local Xcode needed once your build is uploaded. 
npx momentic-mobile assets upload ./path/to/YourApp.app \
  --channel dev \
  --tag 1.0.0
Prefer local simulators? They’re supported, but slower to boot than remote simulators, see iOS simulators for the LOCAL_IOS_DEVICE_TYPE / LOCAL_IOS_APP_PATH setup and boot-time tips.

​
7. Write and run your first test

Open the local editor: 
npx momentic-mobile app
Mobile tests are authored in this local editor (momentic-mobile app), not in the web app. The cloud dashboard at app.momentic.ai is for viewing results, a browser-based creator for mobile tests isn’t available yet.
Create a test, pick the dev channel and 1.0.0 tag, and author a single natural-language step. Save it (the editor writes the .test.yaml to your project), run it from the editor to verify, then run it from the CLI by name: 
npx momentic-mobile run <your-test-name>

​
8. Verify

  • Check the .test.yaml you just authored exists in your project root
  • Open the dashboard and check Runs for the result

​
9. Next steps

iOS app setup

Xcode build, .app bundling, required signing

Simulators

Local vs. remote simulators and device types

CI/CD

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