> ## 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-mobile run

> Run Momentic mobile tests locally and optionally upload results.

Runs Momentic mobile tests in the current project. By default, results are
written to a local directory; pass `--upload-results` to send them to the
dashboard after the run completes. Requires tests to exist locally as YAML
files.

```bash theme={null}
npx momentic-mobile run --upload-results
```

## Arguments

<ParamField path="[tests...]" type="array">
  Tests to run, given as test file paths, directories, or test-name substrings.
  Defaults to every test in the current project.
</ParamField>

## Common flags

<ParamField path="-c, --config <config>" type="string">
  Path to the Momentic configuration file. Defaults to `momentic.config.yaml` in
  the current directory.
</ParamField>

<ParamField path="--name <name>" type="string">
  Name to associate with this run, used in the dashboard and as the base
  filename for generated reports.
</ParamField>

<ParamField path="-p, --parallel <parallel>" type="string">
  Number of tests to run in parallel. Defaults to `1`. Pass `AUTO` to
  saturate the current shard.

  Remote runs give each test an independent emulator session, so parallelism is
  safe and any org quota is enforced server-side. Local Android runs require a
  distinct AVD per parallel test, running multiple tests against the same
  `--local-avd-id` conflicts. Local iOS runs prefer `parallel=1` because
  concurrent Appium instances share a driver manifest.
</ParamField>

<ParamField path="-y, --yes" type="boolean">
  Skip all confirmation prompts. Enabled by default when `CI` is set.
</ParamField>

## Environment

<ParamField path="--env <env>" type="string">
  Environment to run tests in. Must exist in the project configuration and takes
  precedence over the default environment configured on the test.
</ParamField>

<ParamField path="--region <region>" type="string">
  Region used for remote emulator sessions. Overrides any region configured at
  the project or environment level. Pass `closest` to autoselect the nearest
  region.
</ParamField>

<ParamField path="--channel <channel>" type="string">
  Override the default release channel for APK selection (e.g., `staging`,
  `dev`). When omitted, falls back to the test's default channel, otherwise no
  APK is installed on emulator initialization.
</ParamField>

<ParamField path="--tag <tag>" type="string">
  Override the version tag within the selected channel. When omitted, uses the
  test's default tag, otherwise the latest uploaded APK in the channel.
</ParamField>

## Filtering

<ParamField path="--labels <labels...>" type="array">
  Only run tests with one of the specified labels.
</ParamField>

<ParamField path="--include <includePatterns...>" type="array">
  Only include tests whose file path matches any of the provided regex patterns.
  The pattern only needs to match part of the path.
</ParamField>

<ParamField path="--exclude <excludePatterns...>" type="array">
  Exclude tests whose file path matches any of the provided regex patterns.
</ParamField>

## Video

<ParamField path="--video [value]" type="boolean | on-fail">
  Record videos of mobile test runs. Accepts `true`, `false`, or `on-fail`.
  Defaults to `on-fail` (videos are recorded but kept only for failing tests).

  ```bash theme={null}
  npx momentic-mobile run --video true         # record every test
  npx momentic-mobile run --video on-fail      # keep videos only for failures
  npx momentic-mobile run --video false        # disable video
  ```
</ParamField>

## Quarantine

<ParamField path="--skip-quarantined" type="boolean">
  Skip quarantined tests entirely. By default, quarantined tests still run but
  their statuses do not affect pipeline status or the process exit code.
</ParamField>

<ParamField path="--only-quarantined" type="boolean">
  Run only quarantined tests, applying their statuses to pipeline status and the
  exit code.
</ParamField>

<ParamField path="--ignore-quarantine" type="boolean">
  Run every test even if it is quarantined. Useful for validating that
  quarantined tests are fixed before moving them out of quarantine.
</ParamField>

## Caching

<ParamField path="--disable-cache" type="boolean">
  Disable step caches entirely. Steps run without cached data and no caches are
  saved.
</ParamField>

<ParamField path="--save-cache" type="boolean">
  Always save updated step caches after successful runs, even on the main and
  other protected Git branches. See [cache saving
  eligibility](/reliability/step-cache#cache-saving-eligibility).
</ParamField>

<ParamField path="--regenerate-cache" type="boolean">
  Run without using any existing caches. Step caches are still saved at the end
  of the run. Useful for refreshing caches after a config change.
</ParamField>

## Visual diff

<ParamField path="--update-golden-files" type="boolean">
  Update locally stored golden files for
  [`visualDiff`](/reference/mobile-commands/visual-diff) steps. Without this
  flag a `visualDiff` step fails when the screenshot differs from its golden;
  missing goldens are always created on first run regardless of this flag.
</ParamField>

## Sharding

<ParamField path="--shard-index <shardIndex>" type="string">
  1-indexed shard to run. Defaults to `1`. Must be less than or equal to
  `--shard-count`.
</ParamField>

<ParamField path="--shard-count <shardCount>" type="string">
  Total number of shards. Defaults to `1` (no sharding).
</ParamField>

## Output

<ParamField path="--output-dir <outputDir>" type="string">
  Directory to store run artifacts (screenshots, logs, results). Defaults to the
  project's `outputDir` or `./test-results`. The directory is cleared at the
  start of a run.
</ParamField>

<ParamField path="--upload-results" type="boolean">
  Upload test results to the Momentic dashboard after the run. Equivalent to
  running `momentic-mobile results upload <outputDir>` once the run finishes.
</ParamField>

<ParamField path="--reporter <reporter>" type="string">
  Output reporter. Pass multiple times to combine reporters
  (e.g. `--reporter=list --reporter=junit`).

  Live reporter renders progress to the terminal as the run unfolds:

  * `list`: per-test rows. Default. On a TTY the running rows redraw in place with
    their current step; on non-TTY each test commits a single row when it
    finishes.

  File reporters write post-run output to `--reporter-dir`. The following are
  supported for mobile runs:

  * `json`
  * `junit`
  * `allure`
  * `allure-json`
  * `buildkite-json`
</ParamField>

<ParamField path="--reporter-dir <reporterDir>" type="string">
  Directory where reporter output is saved. Defaults to `./reports`. Filenames
  derive from `--name` (or the project name).
</ParamField>

<ParamField path="--log-level <logLevel>" type="string">
  Logging verbosity. One of `error`, `warn`, `info`, or `debug`.
</ParamField>

## Local devices

<ParamField path="--local-avd-id <id>" type="string">
  Force tests to use a specific local Android Virtual Device (AVD). Overrides
  all configuration at the test and environment level.
</ParamField>

<ParamField path="--local-apk-path <path>" type="string">
  Override the APK installed on emulator initialization. Requires
  `--local-avd-id`.
</ParamField>

<ParamField path="--local-ios-device-type <deviceType>" type="string">
  Force tests to use a specific local iOS simulator device type. Accepts any
  option Xcode supports when creating a new simulator (e.g., `"iPhone 17"`).
</ParamField>

<ParamField path="--local-app-path <path>" type="string">
  Override the iOS app installed on simulator initialization. Requires
  `--local-ios-device-type`.
</ParamField>

## CI

<ParamField path="--timeout-minutes <timeoutMinutes>" type="string">
  Maximum total run time, in minutes. When reached, running tests stop and the
  current results are printed.
</ParamField>

## Examples

Run every test and upload to the dashboard:

```bash theme={null}
npx momentic-mobile run --upload-results
```

Run a sharded Android pipeline against a staging APK:

```bash theme={null}
npx momentic-mobile run --channel staging --shard-index 1 --shard-count 4 --reporter junit
```

Run against a local iOS simulator with a freshly built app:

```bash theme={null}
npx momentic-mobile run --local-ios-device-type "iPhone 17" --local-app-path ./build/App.app
```