Skip to main content

Documentation Index

Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 from your terminal, or copy the prompt below into an LLM coding agent (Cursor, Claude, etc.): 
npx @momentic/wizard@latest
It gets you to a passing iOS test in about two minutes: sign-in, install, sample test run against a remote simulator, and editor MCP setup, all in one flow.

Set up Momentic for an iOS project end to end via the onboarding wizard.

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

​
1. Prerequisites

  • Node.js 20.19.0+, 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  # v20.19.0 or higher

​
2. Install

npm install --save-dev momentic-mobile@latest

​
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

In Xcode, select Product, then Build For, then Testing. This produces a .app bundle that Momentic can install on a simulator. Full instructions are in iOS app setup.

​
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? See iOS simulators for the LOCAL_IOS_DEVICE_TYPE / LOCAL_IOS_APP_PATH setup.

​
7. Write and run your first test

Open the local editor: 
npx momentic-mobile app
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.