> ## 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.

# iOS

> Set up Momentic for an iOS app and run your first mobile test.

<Info>
  Momentic supports **local and remote iOS simulators**. Real devices are not
  supported. Local simulators require macOS; remote simulators run from any
  host.
</Info>

## Prerequisites

The wizard and manual setup both require:

* **Node.js** 22.12.0+ in the 22.x line, 24.x, or 26.x. See the
  [Node.js release list](https://nodejs.org/en/about/previous-releases/) for
  supported release lines.
* A `package.json` in your project (run `npm init -y` if you don't have one)
* A Momentic account; [sign up](https://app.momentic.ai) to generate an API key

Manual setup also requires a build of your app. See
[iOS app setup](/docs/platforms/ios/app-setup). For local simulators, you
additionally need **macOS**, **Xcode**, **Xcode Command Line Tools**, and
**[idb](https://fbidb.io/docs/installation)**. The recommended wizard path uses
a remote simulator and does not require local Xcode or an app build for its
sample run.

```bash theme={null}
node -v  # need 22.12.0+ in 22.x, 24.x, or 26.x
```

## Install via the wizard (recommended)

Run the onboarding wizard in your terminal. It signs you in through the browser,
installs Momentic, runs a sample test against a remote simulator, and sets up
the editor MCP server.

```bash theme={null}
npx @momentic/wizard@latest
```

## Setup with coding agent

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:

<Prompt description="Set up Momentic for an iOS project end to end via the onboarding wizard, non-interactively." actions={["copy", "cursor", "claude"]}>
  Set up Momentic for iOS testing in this project by running the onboarding
  wizard non-interactively.

  First, get an API key. Check whether one is already available:

  * If `MOMENTIC_API_KEY` is set in the environment, or `~/.momentic/auth.json`
    exists from a previous sign-in, reuse it and skip ahead to running the wizard.
  * Otherwise, you cannot sign in through the browser yourself. Ask me to sign up
    at [https://app.momentic.ai](https://app.momentic.ai), create an API key at
    [https://app.momentic.ai/settings/api-keys](https://app.momentic.ai/settings/api-keys), and paste it back. Wait for the
    key, then export it:

  ```bash theme={null}
  export MOMENTIC_API_KEY=<the key I give you>
  ```

  Then run the wizard non-interactively. `npx --yes` auto-confirms the one-time
  package download, and the wizard's own `-y` flag resolves every prompt from
  flags, env, and defaults (reading the API key from `MOMENTIC_API_KEY`), so the
  command never blocks on input:

  ```bash theme={null}
  npx --yes @momentic/wizard@latest -y --platform ios --editor-tools skills
  ```

  This installs `momentic-mobile` as a dev dependency, scaffolds
  `momentic.config.yaml` plus a sample test under `ios/`, and runs the sample test
  end to end against a remote simulator (no local Xcode required).
  `--editor-tools` controls coding-agent setup: pass a comma-separated list to
  register the Momentic MCP server and install skills (for example `cursor,skills`
  or `claude-code,skills`), `all` to configure every detected agent, or `none` to
  skip. Omit the flag to auto-detect installed agents.

  The sample run uses a remote simulator, so it needs no local setup. To run tests
  against local simulators later, you'll need macOS, Xcode, Xcode Command Line
  Tools (`xcode-select --install`), and [idb](https://fbidb.io/docs/installation).

  When it finishes, confirm the sample test passed and that `momentic.config.yaml`
  (plus the sample `ios/contacts.test.yaml`) was created in the project.
</Prompt>

## Manual setup

<div id="1-install" role="heading" aria-level={4} className="mt-8 text-lg font-semibold">
  {"1. Install"}
</div>

```bash theme={null}
npm install --save-dev momentic-mobile
```

<div id="2-authenticate" role="heading" aria-level={4} className="mt-8 text-lg font-semibold">
  {"2. Authenticate"}
</div>

**Option A**: sign in with your browser (recommended):

```bash theme={null}
npx momentic-mobile login
```

This opens a browser-based login flow and saves credentials to
`~/.momentic/auth.json`. The CLI automatically uses this file when
`MOMENTIC_API_KEY` is not set.

**Option B**: use an API key:

Create an API key in the [dashboard](https://app.momentic.ai/settings/api-keys),
then export it:

```bash theme={null}
export MOMENTIC_API_KEY=your-api-key-here
```

<div id="3-initialize" role="heading" aria-level={4} className="mt-8 text-lg font-semibold">
  {"3. Initialize"}
</div>

```bash theme={null}
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](#install-via-the-wizard-recommended) instead.)

<div id="4-connect-your-coding-agent" role="heading" aria-level={4} className="mt-8 text-lg font-semibold">
  {"4. Connect your coding agent"}
</div>

The wizard configures Momentic's MCP server and installs agent skills for you.
For manual setup, follow the [MCP setup guide](/docs/coding-agents/mcp-server) to
connect your editor and install the skills your coding agent needs.

<div id="5-build-your-app" role="heading" aria-level={4} className="mt-8 text-lg font-semibold">
  {"5. Build your app"}
</div>

Momentic installs a Simulator `.app` bundle. Build it with the tab that matches
your stack. Full instructions are in [iOS app setup](/docs/platforms/ios/app-setup);
for more cross-platform detail see [Cross-platform](/docs/quickstart/cross-platform).

<Tabs>
  <Tab title="Native (Swift)">
    In Xcode, select **Product**, then **Build For**, then **Testing**. This
    produces a `.app` bundle that Momentic can install on a simulator.
  </Tab>

  <Tab title="React Native">
    Open `ios/<YourApp>.xcworkspace` in Xcode, then **Product**, **Build For**,
    **Testing** to produce a Simulator `.app`.
  </Tab>

  <Tab title="Expo">
    Generate the native project, then build it like a React Native app:

    ```bash theme={null}
    npx expo prebuild
    ```

    Or build a Simulator `.app` directly with EAS:

    ```bash theme={null}
    eas build --platform ios --profile preview --local
    ```
  </Tab>

  <Tab title="Flutter">
    ```bash theme={null}
    flutter build ios --simulator   # .app in build/ios/iphonesimulator/
    ```
  </Tab>
</Tabs>

<div id="6-upload-your-build-remote-simulators" role="heading" aria-level={4} className="mt-8 text-lg font-semibold">
  {"6. Upload your build (remote simulators)"}
</div>

Remote simulators are managed by Momentic, so you do not need local Xcode once
your build is uploaded.

```bash theme={null}
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](/docs/platforms/ios/simulators) for the
`LOCAL_IOS_DEVICE_TYPE` / `LOCAL_IOS_APP_PATH` setup and boot-time tips.

<div id="7-write-and-run-your-first-test" role="heading" aria-level={4} className="mt-8 text-lg font-semibold">
  {"7. Write and run your first test"}
</div>

Open the [local editor](/docs/local-app):

```bash theme={null}
npx momentic-mobile app
```

<Note>
  Mobile tests are authored in this local editor (`momentic-mobile app`), not in
  the web app. The cloud dashboard at [app.momentic.ai](https://app.momentic.ai)
  is for viewing results, a browser-based creator for mobile tests isn't
  available yet.
</Note>

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:

```bash theme={null}
npx momentic-mobile run <your-test-name>
```

<div id="8-verify" role="heading" aria-level={4} className="mt-8 text-lg font-semibold">
  {"8. Verify"}
</div>

* Check the `.test.yaml` you just authored exists in your project root
* Open the [dashboard](https://app.momentic.ai) and check **Runs** for the
  result

## Next steps

<CardGroup cols={3}>
  <Card title="iOS app setup" icon="mobile" href="/docs/platforms/ios/app-setup">
    Xcode build, .app bundling, required signing
  </Card>

  <Card title="Simulators" icon="tablet-screen-button" href="/docs/platforms/ios/simulators">
    Local vs. remote simulators and device types
  </Card>

  <Card title="CI/CD" icon="play" href="/docs/running-tests/ci/github-actions">
    Run mobile tests on every pull request
  </Card>
</CardGroup>

Clone [momentic-ai/examples](https://github.com/momentic-ai/examples) for a full
working example.