CLI Reference

Sign in once per account, then switch without entering passwords again until a session expires. Updating an account keeps your other saved logins. Install the latest CLI to use these commands.

In a folder containing mach.config.json, login and switch remember the account for that project folder. Other project folders keep their own preferences, so two terminals can work with different accounts. Outside a project, switch changes the default account. The --global option changes the default without overriding existing project preferences.

Selection order: MACH_TOKEN, then --account, then the project preference, then the default account. A missing selected login stops the command instead of selecting a different account. For monorepos, --config or MACH_CONFIG_PATH selects the config directory whose account preference is used. Preferences and tokens are stored on your computer, outside the repository; no account configuration needs to be committed.

A running command keeps its starting account through API requests, token refresh and retries. Switching in another terminal affects future commands. Builds and submissions still check project permissions before starting, and show the selected account and project. CI and cloud runners continue using MACH_TOKEN; saved accounts do not override it.

Logout removes local sessions without cancelling running jobs or changing a running command’s in-memory session. Project preferences remain as a safety guard; log in or switch before using an affected project, or clear its preference explicitly.

Sessions and project preferences live in ~/.mach/accounts.json with owner-only read/write permissions. Passwords are never saved. The token file is not an encrypted vault, so protect your OS account and backups. Existing credentials.json logins remain readable and migrate on the first login, switch, logout or refresh. Account lists and JSON output show names and selection metadata, never tokens.

Mach Web Hosting

Mach Web Hosting is separate from the AWS mach host command. It uploads a finished Expo, React Native Web, or Flutter web build to private Mach storage and serves it through the managed delivery layer with immutable preview URLs plus Production and Staging aliases.

Android cloud build architecture

Android cloud builds launch on one-time EC2 Spot instances by default. The API uploads the full build script and secrets to S3, starts a small bootstrap on the builder, and the runner uploads artifacts before reporting final status back to Mach.

On-demand is used only for spot interruption recovery. If AWS interrupts an active spot build, the runner reports `interrupted` with its instance id. The API relaunches that same build once on on-demand capacity, refreshes the presigned artifact URLs, updates the active instance id, and ignores stale callbacks from the old instance.

After artifacts and final status are safe, Android builders terminate. The runner shuts down with terminate behavior, and the API also calls EC2 terminate as a backup cleanup step. Build instances are tagged with `Service=mach-android-build`, `BuildId`, `ProjectId`, `MarketMode`, and `KeepInstance` for AWS audits.

Add Maestro flows to `.maestro`. When you run `mach maestro --maestro-flows .maestro` from the project repo, Mach uploads that local flow folder for the managed run. If the folder is not available, Mach falls back to the build source snapshot. Emulator runners need x86_64 ABI support; build with `--maestro`, use an e2e/Maestro profile name, or set `android.emulator` to true.

Use `--maestro-env <name>` when flows need credentials or other runtime values. Local runs forward only variables that exist in the shell or loaded dotenv environment; the startup log should list every forwarded name. Existing projects keep their legacy managed-run behaviour. Save isolated, project-scoped credentials under Secrets → E2E test variables to avoid supplying test passwords from CI.

Choose Secrets → E2E test variables, select an environment, and use Add variable to save test-only values under Global or your profile’s environment. Use the exact variable names from your test files; no Maestro-specific prefix is required. Newly saved variables are used automatically, with no portal profile mapping or enablement form. Managed iOS runners need MACH CLI 2.13.0 or later for private test output handling.

Precedence is explicit --maestro-env values, then the selected profile’s environment secrets, then Global E2E secrets. The CLI resolves inheritance and platform-specific environment overrides from mach.config.json; when environment is omitted, it uses the same profile-name scope fallback as builds. Dashboard runs use the environment recorded with the build. Older builds can use their existing legacy mapping or be tested from the linked CLI project. Scoped secrets are never resolved by guessing when context is missing. Requested variable names are checked before runner launch or billing. Automatic attempts keep one encrypted snapshot; a newly queued rerun resolves current values.

Test values are encrypted and isolated from application build variables, mach env pull and environment exports. Developers see resolved names and their environment; only administrators can change values. There is no reveal or export action. Change history records actors, names and times without values. Existing legacy configurations and explicit pauses remain unchanged until an administrator saves variables with the new workflow or chooses Use automatically. Queued and running tests are unchanged.

Updated runners scrub known values and common encodings from streamed logs, errors and textual reports. An incompatible runner cannot retrieve central values. Screenshots and recordings cannot be reliably redacted; authenticated-run evidence requires developer or higher project access and uses expiring file links. Use sample test accounts and avoid logging secrets or placing them in screenshots. Local --local runs continue to use local variables and do not download stored test credentials. No new scheduler or publishing permission is created by this feature.

Run browser E2E tests with Playwright from your Mac, workstation, or existing CI runner. The first run adds @playwright/test through the project's package manager and ensures Chromium is available. Mach records a safe Playwright · Web · Local result in E2E Tests, but never starts a Mach browser runner.

The initial setup saves Playwright to the project's development dependencies, so commit its lockfile and let the pipeline's ordinary dependency-install step restore it. Mach checks for Chromium on every run, but Playwright only downloads it when its browser cache is empty. Cache `~/.cache/ms-playwright` on short-lived Linux CI workers to avoid repeat downloads. Use `--no-setup` for an image that already has both the dependency and browser.

Screenshots, videos, traces, reports, test source, environment values, and browser output stay on the local runner. The dashboard stores only the status, timing, chosen configuration name, browser project, and a base URL origin when you provide one. Local runs have no Mach charge.

The local agent exposes device discovery and install endpoints on port 7070. It is local-only, so it can be started, installed, checked, or stopped without Dashboard authentication.

Use `--json-output` in Bitbucket, GitHub Actions, or any CI runner when another step needs the Dashboard build URL. The file contains `buildId`, `status`, `platform`, and `url`.

Replace EAS commands with Mach commands, install the Mach CLI in each step, and authenticate with `MACH_TOKEN`. Store builds should use `--auto-version`, `android.versionCode: auto`, or `ios.buildNumber: auto` so Google Play and App Store Connect accept upgrades.

Android submit runs directly against the Google Play Developer API from the CI runner. iOS submit queues a Mach submission and runs on the configured macOS runner; runner provider details remain internal and users see the Mach submission URL.

Name access tokens after the automation that uses them, such as `BitbucketPipeline` or `MacMiniRunner`. Build and submission rows use that identity for Created by without storing personal email/name values on the run record.

In Settings → Access Tokens, Edit lets you rename a token, change its project access, or shorten its expiry while keeping the same MACH_TOKEN value. Review and confirm any project access change; select one or more projects, or choose All projects as an exclusive option. Excluded projects will no longer accept the token. Rotate creates a replacement when you need to extend or renew validity. Expired and revoked tokens cannot be edited or reactivated. Revoke always asks for confirmation; Keep token leaves it active.

Google Play service keys are package-scoped store automation credentials. They are separate from Android keystores and are required for Google Play submission for the exact package id.

App Store Connect API keys are used for iOS TestFlight submission and submit metadata. Mach stores the key id, issuer id, Apple Developer Team ID, and provider/team metadata so submit commands do not require Apple ID prompts.

Android submit reads `submit.production.android.track` and `submit.production.android.releaseStatus` from config. Valid release statuses are `completed`, `draft`, `halted`, and `inProgress`; the default is `completed`.