@radhya/mach 1.2.0 → 1.3.1

package/README.md

@@ -1,8 +1,8 @@
 # Mach CLI
 
-**Cloud Build Orchestrator for React Native & Expo**
+**Cloud Build & Delivery for React Native, Expo, and Flutter**
 
-Mach is a powerful CLI that lets you build, sign, and submit React Native & Expo apps to the App Store and Google Play — all from the cloud. No more local build headaches.
+Mach is a CLI that lets you build, sign, and submit React Native and Expo apps from the cloud. Flutter support is modeled in configuration and documentation so it can be added without changing the command surface.
 
 ## Installation
 
@@ -16,10 +16,7 @@ npm install -g @radhya/mach
 # Login to Mach Dashboard
 mach login
 
-# Initialize a new project
-mach init
-
-# Link an existing project
+# Link your project
 mach link
 
 # Run a cloud build
@@ -29,108 +26,265 @@ mach build --platform android
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `mach login` | Login to Mach Dashboard |
-| `mach init` | Create a new Mach project |
-| `mach link` | Link local directory to a Mach project |
-| `mach me` | Display current user details |
-| `mach build` | Run a cloud build (iOS / Android) |
-| `mach submit` | Automated store submission (App Store / Google Play) |
-| `mach credentials` | Interactive credential management (iOS / Android) |
-| `mach env` | Manage environment variables |
-| `mach config` | Show resolved configuration for a profile |
-| `mach start` | Start the development server (Metro) |
-| `mach host` | Setup AWS S3 static hosting with CloudFront |
-| `mach sitemap` | Generate sitemap.xml from Expo Router |
-| `mach audit` | Run automated security audit on the project |
-
-### Legacy Commands
-
-| Command | Description |
-|---------|-------------|
-| `mach credentials:setup` | Automated credential provisioning |
-| `mach credentials:service` | Upload service credentials (ASC API Key / Google Service JSON) |
+| Command                    | Description                                                        |
+| -------------------------- | ------------------------------------------------------------------ |
+| `mach login`               | Authenticate with Mach Dashboard                                   |
+| `mach logout`              | Remove saved local Mach credentials                                |
+| `mach init`                | Create a new Mach project                                          |
+| `mach link`                | Link local directory to an existing project                        |
+| `mach me`                  | Show current logged-in user                                        |
+| `mach build`               | Start a cloud build (iOS / Android)                                |
+| `mach maestro`             | Queue managed Maestro tests for a build or artifact                |
+| `mach update`              | Deploy an OTA update to a channel or branch                        |
+| `mach submit`              | Submit to App Store or Google Play                                 |
+| `mach credentials`         | Manage iOS certificates, provisioning profiles & Android keystores |
+| `mach credentials:service` | Upload App Store Connect or Google Play service credentials        |
+| `mach env`                 | Manage, list, and download environment variables and secrets        |
+| `mach config`              | Show resolved configuration for a build profile                    |
+| `mach start`               | Start the Metro development server                                 |
+| `mach device`              | Register test devices for ad-hoc distribution                      |
+| `mach audit`               | Run automated security checks on your project                      |
+| `mach agent`               | Manage the local device discovery agent for Install Hub            |
+| `mach host`                | Set up S3 static hosting and CloudFront                            |
+| `mach sitemap`             | Generate sitemap.xml from Expo Router app routes                   |
+
+## Managed Maestro Testing
+
+Mach's E2E testing layer is being implemented to run Maestro without requiring Maestro Cloud:
+
+```bash
+mach build android --profile e2e-test --maestro
+mach maestro --latest --platform android --profile e2e-test
+mach maestro --build-id <buildId>
+mach maestro --local --build-id <buildId>
+mach maestro --build-id <buildId> --maestro-use-build-source
+mach maestro --build-id <buildId> --wait
+mach maestro --latest --platform ios --maestro-env MAESTRO_TEST_EMAIL --maestro-env MAESTRO_TEST_PASSWORD
+mach maestro --platform ios --local --maestro-flows .maestro-authenticated --maestro-env MAESTRO_TEST_EMAIL --maestro-env MAESTRO_TEST_PASSWORD
+```
+
+Mach manages the test execution infrastructure for you, so projects do not need a separate Maestro Cloud setup.
+Managed Android Maestro runs need an APK artifact and a `.maestro` flow file or directory. By default, `mach maestro --maestro-flows .maestro` uploads the local flow folder for that run when the path exists in the current project. If the local path is not present, Mach falls back to the build source snapshot.
+Managed Android runners use emulators, so the tested APK must include `x86_64`. Mach automatically includes emulator ABI support when you build with `--maestro`, when the profile name looks like `maestro`/`e2e`/`test`, or when the build profile sets `"android": { "emulator": true }`.
+Managed Maestro is billed from the Pay as you go wallet after the runner completes. Default pricing is $0.50 for the first 15 minutes, then $0.10 per additional 10-minute block; admins can change these rates from Dashboard Admin > Pricing.
+Use `mach maestro --local` to run the same flows on your connected local emulator/device. With `--build-id`, Mach downloads and installs the build artifact first; without a build or artifact flag, it runs against the app already installed locally.
+Use `--maestro-env <name>` for local or managed runs that need test credentials or other dynamic values. The flag is repeatable and also accepts comma-separated names. Local runs forward only names that exist in the shell or loaded dotenv environment, and the startup log lists every forwarded name. Managed runs store requested values encrypted, pass them to the iOS or Android Maestro command, redact values from runner logs, and fall back to the Mach server environment when a value is not present in the CLI environment.
+
+Useful options:
+
+| Flag                        | Description                                                   |
+| --------------------------- | ------------------------------------------------------------- |
+| `--maestro`                 | Queue tests automatically after a successful `mach build`     |
+| `--maestro-flows <path>`    | Flow file or directory, defaults to `.maestro`                |
+| `--maestro-device <name>`   | Managed runner device profile, defaults to Android Pixel 6    |
+| `--maestro-retries <n>`     | Retry count for failed runs, from 0 to 10                     |
+| `--maestro-record`          | Enable recording when supported by the runner                 |
+| `--maestro-use-build-source` | Use flows from the build source snapshot instead of local upload |
+| `--maestro-env <name>`      | Forward one env var to Maestro; repeat or comma-separate names            |
+| `--local`                   | Run `maestro test` locally instead of queueing a cloud runner |
+| `--wait`                    | Wait for managed tests and exit non-zero if the run fails     |
+| `--wait-timeout <minutes>`  | Maximum time to wait for a managed run, defaults to 60        |
+| `--wait-interval <seconds>` | Polling interval for `--wait`, defaults to 15                 |
 
 ## Cloud Builds
 
-Build your apps on cloud infrastructure using AWS Spot Instances — fast, cost-effective, and fully automated.
+Trigger a build in the cloud — Mach handles zipping, uploading, compiling, and returning your IPA or APK.
 
 ```bash
-# iOS build
+# iOS build (production)
 mach build --platform ios --profile production
 
 # Android build
 mach build --platform android --profile production
 
-# Local build
+# Build locally
 mach build --platform ios --local
+```
+
+Installable artifacts are downloaded through Mach public file routes, not raw S3 URLs. Public build pages and QR install links use the configured files domain (for example `https://files.getmach.dev`) so users do not see bucket names or presigned S3 URLs.
+
+### Framework Selection
+
+Mach does not auto-detect your app framework during builds. The build framework is declared in `mach.config.json` and is treated as the source of truth:
 
-# Dry run (generate build script without launching)
-mach build --platform android --dry-run
+```json
+{
+  "framework": "react-native"
+}
 ```
 
+Supported values:
+
+| Value            | Status       | Build behavior                                                                 |
+| ---------------- | ------------ | ------------------------------------------------------------------------------ |
+| `react-native`   | Supported    | Uses committed `ios/` and `android/` native projects. No Expo prebuild runs.   |
+| `expo`           | Supported    | Runs Expo prebuild before native compilation and applies Expo-specific guards. |
+| `flutter`        | Planned      | Reserved in config/docs. Builds fail clearly until Flutter builders are added. |
+
+`mach init` and `mach link` create `framework: "react-native"` by default. Change it to `"expo"` for Expo projects before running builds. This explicit config prevents a React Native change from affecting Expo projects, and avoids fragile package scanning in CI.
+
+Use the framework guide that matches your app. The command surface stays the same; only `framework` changes the build pipeline:
+
+- [Choose a framework](docs/frameworks/README.md)
+- [Bare React Native](docs/frameworks/react-native.md)
+- [Expo](docs/frameworks/expo.md)
+- [Flutter](docs/frameworks/flutter.md)
+
+## Local Device Agent
+
+The Install Hub can install builds on connected local devices when the Mach agent is running on your machine.
+
+```bash
+# Run in the foreground
+mach agent
+
+# Install as a background login service/task
+mach agent install
+
+# Inspect or control the background agent
+mach agent status
+mach agent restart
+mach agent stop
+mach agent uninstall
+```
+
+`mach agent` is local-only and does not require Dashboard authentication. It exposes device discovery and install endpoints on `http://127.0.0.1:7070`.
+
 ### Build Options
 
-- `--platform <os>` — Target platform: `ios` or `android` (required)
-- `--profile <name>` — Build profile from `mach.config.json` (e.g., `production`, `staging`, `development`)
-- `--auto-version` — **(Android)** Automatically resolve and increment versionCode via Google Play API
-- `--local` — Run build on local machine
-- `--dry-run` — Generate script without launching
-- `--verbose` — Enable verbose logging
-- `--simulator` — Build for iOS Simulator (no signing required)
+| Flag             | Description                                                                      |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `--platform`     | `ios` or `android` (required)                                                    |
+| `--profile`      | Build profile from `mach.config.json` (default: `production`)                    |
+| `--local`        | Run build on local machine                                                       |
+| `--dry-run`      | Generate build script without running it                                         |
+| `--simulator`    | iOS Simulator build (no signing needed)                                          |
+| `--auto-version` | Force Android versionCode or iOS buildNumber lookup from the store               |
+| `--auto-submit`  | Submit the successful build to App Store Connect or Google Play                  |
+| `--verbose`      | Enable detailed build logging                                                    |
+| `--json-output`  | Write build metadata (`buildId`, Dashboard URL, status) to a JSON file for CI/CD |
 
-## Automated Versioning (Android)
+### CI Build URLs
 
-Mach can automatically resolve your next `versionCode` by querying the Google Play Store. This prevents "Duplicate Version Code" rejection errors.
+Use `--json-output` when a pipeline needs the Dashboard URL for Slack, deployment notes, or downstream steps:
 
-### Setup
-Ensure you have uploaded a **Google Service Account JSON** to the Mach Dashboard under Service Credentials.
+```bash
+mach build --platform android --profile production --json-output mach-android-build.json
+ANDROID_URL=$(node -pe "require('./mach-android-build.json').url")
+```
+
+The JSON file includes:
 
-### usage
-Set the version code to `"auto"` in your config:
 ```json
-"android": {
-  "versionCode": "auto"
+{
+  "status": "success",
+  "buildId": "00000000-0000-0000-0000-000000000000",
+  "platform": "android",
+  "profile": "production",
+  "url": "https://getmach.dev/build/00000000-0000-0000-0000-000000000000"
 }
 ```
-Or pass the flag via CLI:
-```bash
-mach build --platform android --auto-version
-```
 
-> [!TIP]
-> Mach queries all tracks (Internal, Alpha, Beta, Production), finds the highest existing version, and increments it by 1 for your new build.
+Set `MACH_DASHBOARD_URL` only for local or staging dashboards. Production build links default to `https://getmach.dev`.
+
+### Bitbucket Pipelines
+
+Mach works in Bitbucket through a Dashboard access token. Create a token in **Dashboard → Settings → Access Tokens**, save it as `MACH_TOKEN`, and use `--json-output` when a pipeline needs the Mach build URL for later steps.
+
+```yaml
+image: node:24.13.1
+
+definitions:
+  steps:
+    - step: &build-android
+        name: Build Android
+        size: 2x
+        caches:
+          - node
+        script:
+          - npm ci
+          - npm install -g @radhya/mach@latest
+          - mach build --platform android --profile production --auto-version --json-output mach-android-build.json
+
+    - step: &submit-android
+        name: Submit Android
+        size: 2x
+        caches:
+          - node
+        script:
+          - npm ci
+          - npm install -g @radhya/mach@latest
+          - mach submit --latest --platform android --profile production
+```
 
+Android submission uses the Google Play Developer API directly, so Bitbucket/Linux runners do not need Ruby or Fastlane for `.aab` uploads. Mach retries transient Play API failures before failing and records Android submissions in the Dashboard. iOS submission is queued through Mach, so the public command is the same from macOS, Linux, Windows, or CI. Users see the Mach submission URL and status.
 
-## Store Submission
+Before enabling CI, make sure `mach.config.json` is committed, `MACH_TOKEN` is configured as a secure CI variable, credentials are uploaded in the Dashboard, and Android service credentials are attached to the exact package id.
 
-Automate your App Store and Google Play submissions directly from the CLI.
+For iOS submit, the user-facing command is universal:
 
 ```bash
-# Submit to App Store
-mach submit --platform ios
-
-# Submit to Google Play (internal track)
-mach submit --platform android --track internal
+mach submit --latest --platform ios --profile production
 ```
 
+Mach handles the managed macOS submission environment internally. No provider-specific macOS job needs to be added to a user's CI configuration.
+
 ## Credential Management
 
-Manage iOS certificates, provisioning profiles, Android keystores, and service credentials — all in one place.
+Manage iOS certificates, provisioning profiles, Android keystores, and App Store Connect API keys — all stored securely in the Dashboard.
 
 ```bash
 # Interactive credential manager
 mach credentials
+```
+
+Mach walks you through each step: choosing a bundle ID, picking a distribution type (development / ad-hoc / App Store), and syncing certificates. Everything is encrypted at rest and injected at build time.
+
+For iOS development and ad-hoc profiles, Mach also asks which registered devices should be included. After registering the selected devices with Apple, Mach refreshes the provisioning profile so the uploaded profile includes those devices instead of reusing an older cached profile.
+
+### Apple Developer Team Selection
 
-# Legacy: Automated provisioning
-mach credentials:setup --platform ios
-mach credentials:setup --platform android
+For iOS credentials, Mach asks for your Apple ID and then lists the Apple Developer teams connected to that account through `@expo/apple-utils`. If the account has multiple teams, choose the team to use for signing; if Apple cannot return the list, Mach falls back to manual Team ID entry. Fastlane is still used later for the certificate/profile sync, but it is no longer required just to display the team picker.
 
-# Upload service credentials (ASC API Key / Google Service JSON)
-mach credentials:service --platform ios --file key.p8 --key-id XXXXX --issuer-id XXXXX
+Mach saves the selected Team ID to the Dashboard for credential storage. It also asks whether to write the Team ID into `mach.config.json` for the selected profile. Accepting the prompt writes only `submit.<profile>.ios.appleTeamId`; production defaults to yes, while development and staging default to no so local config is not cluttered unless you want profile-specific signing.
+
+### Multiple Bundle IDs
+
+One project can have multiple bundle identifiers (e.g. `com.example.app`, `com.example.app.staging`, `com.example.app.dev`). Each bundle ID has its own independent set of credentials per distribution type. Select or add a bundle ID at the start of `mach credentials` — or skip the prompt with the `--bundle-id` flag for CI:
+
+```bash
+mach credentials --bundle-id com.example.app.staging
 ```
 
+The Dashboard shows each bundle ID as a row. Clicking it reveals its Distribution certificate, Provisioning profile, and Service credentials — matching the same layout as Expo's credentials screen. A **Password stored** badge confirms the P12 export password is saved and will be injected at build time automatically.
+
+### Service Credentials
+
+Service credentials are used for store automation:
+
+- iOS: App Store Connect API key (`.p8`)
+- Android: Google Play service account JSON
+
+Android service credentials are scoped to a package name. This matters when one Mach project contains multiple Android application identifiers.
+
+```bash
+# Android: upload a Google Play service account JSON
+mach credentials:service --platform android --package-name com.example.app --file ~/Downloads/play-service-account.json
+
+# If --package-name is omitted, Mach fetches saved Android package ids
+# from the Dashboard and asks you to select one.
+mach credentials:service --platform android --file ~/Downloads/play-service-account.json
+
+# iOS: upload or create an App Store Connect API key
+mach credentials:service --platform ios
+```
+
+The Dashboard also supports this under **Credentials → Android → package id → Service credentials**. Uploading a Google Play service key under `*` is legacy behavior; store submission now expects the service credential to match the Android package being submitted.
+
+App Store Connect keys are used for iOS TestFlight submission and iOS buildNumber auto-increment. Mach stores the key id, issuer id, Apple Developer Team ID, and App Store Connect provider/team metadata so build and submit commands can run without Apple ID prompts.
+
+Google Play service keys are only needed for store automation: Android submission and Play-backed versionCode resolution. They are not signing credentials. A dev package such as `com.example.app.dev` needs its own Google Play service key only if that exact package exists in Google Play and you explicitly ask Mach to query Play for it.
+
 ## Configuration
 
 Create a `mach.config.json` in your project root:
@@ -138,93 +292,81 @@ Create a `mach.config.json` in your project root:
 ```json
 {
   "projectId": "your-project-id",
+  "framework": "react-native",
   "name": "MyApp",
   "slug": "my-app",
-  "scheme": "myapp",
+  "nodeVersion": "24",
   "ios": {
     "bundleIdentifier": "com.example.myapp",
-    "teamId": "XXXXXXXXXX"
+    "appleTeamId": "ABCDE12345",
+    "ascAppId": "1234567890",
+    "buildNumber": "auto"
   },
   "android": {
     "package": "com.example.myapp",
     "versionCode": "auto"
-  }
-}
-```
-
-### Build Profiles
-
-Define multiple build profiles under the `build` key. Profiles support deep inheritance via `extends`.
-
-```json
-{
-  "projectId": "your-project-id",
-  "name": "MyApp",
-  "slug": "my-app",
-  "scheme": "myapp",
-  "android": { "package": "com.example.myapp" },
-  "ios": { "bundleIdentifier": "com.example.myapp" },
+  },
   "build": {
-    "base": {},
     "development": {
-      "extends": "base",
       "developmentClient": true,
+      "distribution": "development",
       "environment": "development"
     },
     "staging": {
-      "extends": "base",
       "distribution": "internal"
     },
     "production": {
-      "extends": "base",
       "distribution": "store"
     }
   },
   "submit": {
     "production": {
-      "android": { "track": "internal" },
+      "android": { "track": "internal", "releaseStatus": "completed" },
       "ios": {
-        "ascAppId": "1234567890",
-        "appleTeamId": "XXXXXXXXXX"
+        "ascAppId": "",
+        "appleTeamId": ""
       }
     }
   }
 }
 ```
 
-### Profile Properties
+### Root Properties
 
-| Property | Description |
-|----------|-------------|
-| `extends` | Inherit settings from another profile (recursive) |
-| `environment` | Map to a Dashboard Secret Environment (`development`, `staging`, `production`). Defaults to profile name. |
-| `developmentClient` | `true` to build with `expo-dev-client` |
-| `distribution` | `internal` (TestFlight/Play Console) or `store` (Production) |
-| `preBuild` / `postBuild` | Reference a script or run a raw command |
-| `envGroups` | Array of environment group names to merge into this profile |
+| Property      | Description                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------------------------------------- |
+| `projectId`   | Auto-generated UUID linking to your Dashboard project                                                           |
+| `framework`   | Required build framework: `react-native`, `expo`, or `flutter`. Builds never infer this from `package.json`     |
+| `name`        | App display name                                                                                                |
+| `nodeVersion` | Node.js version to use on the build machine (e.g. `"24"`, `"20.11.0"`). Switches via nvm before installing deps |
 
-### Platform Overrides
+### Platform Properties
 
-Any property can be overridden per platform using `ios` or `android` blocks:
+| Property               | Description                                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `ios.bundleIdentifier` | iOS bundle ID used for signing, App Store Connect lookup, and submit                                                           |
+| `ios.appleTeamId`      | Optional global Apple Developer Team ID used for iOS signing. Profile-specific `submit.<profile>.ios.appleTeamId` overrides it |
+| `ios.ascAppId`         | App Store Connect app id. Optional when Mach can find the app by bundle ID; recommended for reliable iOS buildNumber lookup    |
+| `ios.buildNumber`      | Set to `"auto"` to let Mach resolve the next iOS CFBundleVersion from App Store Connect and seed the server-side build counter |
+| `android.package`      | Android package name used for signing, Google Play lookup, and submit                                                          |
+| `android.versionCode`  | Set to `"auto"` to let store builds resolve the next versionCode via Google Play                                               |
 
-```json
-{
-  "build": {
-    "development": {
-      "extends": "base",
-      "developmentClient": true,
-      "ios": {
-        "simulator": true,
-        "iosDeploymentTarget": "15.0"
-      }
-    }
-  }
-}
-```
+### Profile Properties
+
+| Property                 | Description                                                                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `extends`                | Inherit settings from another profile                                                                                                          |
+| `environment`            | Dashboard Secret Environment to use (`development`, `staging`, `production`)                                                                   |
+| `developmentClient`      | Expo only: `true` to build with `expo-dev-client`                                                                                              |
+| `distribution`           | `development` for iOS development signing, `internal` for ad-hoc/internal testing builds, or `store` for App Store / Play Store release builds |
+| `android.emulator`       | `true` to include Android emulator ABI support (`x86_64`) for Maestro/e2e APK builds                                                           |
+| `android.architectures`  | Override Android release ABIs, for example `armeabi-v7a,arm64-v8a,x86_64`                                                                      |
+| `preBuild` / `postBuild` | Shell command or script reference to run around the build                                                                                      |
+| `envGroups`              | Array of environment group names to merge into this profile                                                                                    |
 
 ### Environment Groups
 
-Define reusable sets of environment variables shared across profiles:
+Reusable sets of environment variables shared across profiles:
 
 ```json
 {
@@ -241,111 +383,172 @@ Define reusable sets of environment variables shared across profiles:
 }
 ```
 
-### Scripts
+## Secrets & Environment Variables
 
-Define custom build hooks:
+Secrets are encrypted at rest and injected at build time, scoped per environment.
 
-```json
-{
-  "scripts": {
-    "clean": "rm -rf ios/build android/app/build"
-  },
-  "build": {
-    "production": {
-      "preBuild": "scripts.clean"
-    }
-  }
-}
+```bash
+# Add a secret
+mach env set API_URL=https://api.example.com SECRET_KEY=xxx
+
+# List all secrets
+mach env list
+
+# Download development secrets to .env.local
+mach env pull
+
+# Download a specific environment
+mach env pull --environment staging
+mach env pull --environment production --out .env.production.local
+
+# Replace an existing local env file
+mach env pull --environment development --out .env.local --overwrite
 ```
 
-## Environment Variables
+`mach env pull` downloads decrypted secrets for local development. It defaults to `--environment development` and `--out .env.local`. The exported file includes `global` secrets plus the selected environment's overrides. Mach refuses to overwrite an existing file unless `--overwrite` is provided. `mach env download` and `mach env export` are aliases for the same behavior.
+
+Mach includes the resolved environment in the build fingerprint, so development, staging, and production builds do not reuse a native build cache when their injected variables differ. If a stored secret cannot be decrypted, Mach surfaces that as a configuration problem instead of silently injecting `[Decryption Failed]` into a production binary.
+
+### Android Keystore Passwords
+
+The keystore file and its passwords are stored encrypted in the Dashboard when managed through `mach credentials`. Legacy projects can still provide Android signing passwords as environment-scoped secrets in the Dashboard, but managed credentials are recommended so passwords stay attached to the keystore record.
+
+## Automated Versioning
+
+Mach can automatically determine the next Android `versionCode` and iOS `buildNumber` from the store, then increment safely to prevent duplicate upload rejections.
+
+**Android setup:** Upload a Google Service Account JSON via `mach credentials` → Service Credentials for the exact Android package being queried.
 
-Mach allows you to securely inject secrets directly into your cloud builds without exposing them in your codebase. All secrets are fully encrypted using AES-256-GCM.
+**iOS setup:** Upload or create an App Store Connect API key with `mach credentials:service --platform ios`. Set `ios.ascAppId` in `mach.config.json` when possible so Mach can query the exact App Store Connect app.
+
+**Usage:**
 
 ```bash
-# Set environment variables for the project (Defaults to Secret mode)
-mach env set API_URL=https://api.example.com SECRET_KEY=xxx
+mach build --platform android --auto-version
+mach build --platform ios --profile production --auto-version
+```
 
-# List all variables
-mach env list
+Or in config:
+
+```json
+"android": { "versionCode": "auto" },
+"ios": { "buildNumber": "auto" }
 ```
 
-### Android Keystore Passwords
-For maximum security, your Android Keystore (`.jks`) file is stored in a separate encrypted S3 bucket away from its passwords. 
+When `android.versionCode` is set to `"auto"`, Mach performs the Google Play lookup automatically for Android `store` builds. For `internal` builds, Mach skips the Play lookup by default so development packages do not need Google Play service keys. Pass `--auto-version` on an internal build only when that package is registered in Google Play and should be queried.
+
+When `ios.buildNumber` is set to `"auto"`, Mach queries App Store Connect for the latest uploaded build number and seeds Mach's server-side counter from that value. If App Store Connect has build `81` and Mach's internal counter is still `1`, the next iOS build becomes at least `82`. Concurrent builds are still safe because the Dashboard API increments the counter atomically.
 
-To provide your passwords to the Cloud Builder, you **must** define them as Mach Environment variables (Secrets). Mach will automatically securely decrypt and inject them during the Gradle build process.
+This only changes iOS `CFBundleVersion` / build number. It does not bump the public App Store version (`CFBundleShortVersionString`, usually `expo.version` in `app.json`). After a version like `1.17.0` is approved/released, Apple closes that train for new uploads; bump the app version, for example to `1.17.1`, rebuild, then submit.
+
+Regular iOS development builds should set `distribution: "development"` and resolve Apple Development certificates/profiles. For custom profile names, Mach follows the profile fields, not the profile name: `environment` chooses Dashboard secrets, and `distribution` / `iosExportMethod` chooses signing. Dev-client builds can keep `distribution: "internal"` and set `developmentClient: true`; Mach will still use development signing credentials while producing an internal installable artifact.
+
+For Android dev-client builds, Mach defaults to Gradle `assembleDebug` so the output opens the Metro/debug server instead of behaving like a standalone release APK. For iOS dev-client builds, Mach uses the Debug Xcode configuration.
+
+## Store Submission
 
 ```bash
-# Set the master password for the keystore (used for both the Keystore and the Key Alias)
-mach env set KEYSTORE_PASSWORD_PRODUCTION=my_super_secret_password
+# Submit the latest successful build for a profile
+mach submit --latest --platform android --profile production
+mach submit --latest --platform ios --profile production
+
+# Build and submit the exact successful build in one command
+mach build --platform ios --profile production --auto-submit
+mach build --platform android --profile production --auto-submit --submit-track internal
+
+# Android track and release status can be supplied on the command or in mach.config.json
+mach submit --latest --platform android --profile production --track internal --release-status completed
+
+# Staged rollout example
+mach submit --latest --platform android --profile production --track production --release-status inProgress --rollout 0.1
+
+# If Play asks for explicit review handling
+mach submit --latest --platform android --profile production --track internal --changes-not-sent-for-review
 
-# If your Keystore password and Key Alias password differ, you can set both independently:
-mach env set KEYSTORE_PASSWORD_PRODUCTION=my_key_pass KEYSTORE_STORE_PASSWORD_PRODUCTION=my_store_pass
+# Submit a specific build id
+mach submit --platform android --build-id <build-id>
 ```
 
-*(Note: Replace `PRODUCTION` with `STAGING` or `DEVELOPMENT` depending on your targeted build profile).*
+For Android, Mach resolves the package from `mach.config.json` / Expo config and looks for a matching `google_service_account` credential. If none exists, upload it with:
 
+```bash
+mach credentials:service --platform android --package-name com.example.app --file ~/Downloads/play-service-account.json
+```
+
+Android submit reads `submit.<profile>.android.track`, `submit.<profile>.android.releaseStatus`, and optional `submit.<profile>.android.rollout`, falling back to `submit.production.android.*`, then `internal` / `completed`. Valid Google Play release status values are `completed`, `draft`, `halted`, and `inProgress`. Use `rollout` only with `inProgress` or `halted`; it must be greater than `0` and less than `1`.
+
+Android submit does not require Fastlane. Mach uploads the `.aab`, assigns the returned `versionCode` to the requested track, commits the edit through the Google Play Developer API, and records the submission in the Dashboard. Transient Google Play failures are retried up to four times before the command fails.
+
+iOS submit queues a managed submission through Mach. Users and CI call the normal `mach submit --platform ios ...` command, and Mach handles the required macOS upload environment. The Dashboard submission row is connected to the build, records who created it, and is marked failed if the upload fails.
+
+If `--profile` is provided with `--latest`, Mach chooses the latest successful build from that profile only. This avoids accidentally submitting a staging or preprod build to production.
 
 ## Development Server
 
 ```bash
-# Start Metro with profile
 mach start --build-profile development
-
-# Start with tunnel
+mach start --ios
+mach start --android
+mach start --web
 mach start --tunnel
-
-# Clear cache
 mach start --clear
 ```
 
-## Security Audit
+When running an Expo app, `mach start` keeps the normal Expo keyboard flow available:
+press `i` for iOS, `a` for Android, `w` for web, and `r` to reload. Use the flags above when CI/scripts or muscle memory should launch a target immediately.
 
-Run automated security checks on your project:
+## Security Audit
 
 ```bash
 mach audit
 mach audit --severity high
 mach audit --fix
-mach audit --json  # CI/CD friendly output
+mach audit --json   # CI/CD-friendly JSON output
 ```
 
 ## Authentication
 
-### Interactive Login
+### Interactive
 
 ```bash
 mach login
+mach logout
 ```
 
 Credentials are stored in `~/.mach/credentials.json`.
+`mach logout` removes this local credentials file. If `MACH_TOKEN` is set in the shell, unset it separately.
 
 ### CI/CD (Token-based)
 
-Set the `MACH_TOKEN` environment variable for non-interactive authentication:
-
 ```bash
 export MACH_TOKEN=your-personal-access-token
 mach build --platform ios --profile production
 ```
 
-Generate tokens from the Mach Dashboard under Settings > Personal Access Tokens.
+Generate tokens from the Mach Dashboard under **Settings → Access Tokens**.
+Access tokens can be named like CI robots (for example `BitbucketPipeline`). Builds and submissions store the token identity so the Dashboard can show who or what created the run without storing a user's email/name on the build row.
+
+Example CI flow:
+
+```bash
+export MACH_TOKEN=your-personal-access-token
+mach build --platform android --profile production
+mach submit --latest --platform android --profile production
+```
 
 ## Environment Variables Reference
 
-| Variable | Description |
-|----------|-------------|
-| `MACH_TOKEN` | Personal access token for CI/CD (skips login) |
-| `MACH_API_URL` | Override the API endpoint (default: `https://mach-api.securejs.in`) |
-| `MACH_DEBUG` | Enable debug logging |
-| `MACH_P12_PASSWORD` | iOS certificate password (avoids interactive prompt) |
+| Variable            | Description                                                     |
+| ------------------- | --------------------------------------------------------------- |
+| `MACH_TOKEN`        | Personal access token for CI/CD (skips login)                   |
+| `MACH_DEBUG`        | Set to `1` to print resolved build profile and platform details |
+| `MACH_P12_PASSWORD` | iOS certificate password (avoids interactive prompt)            |
 
 ## Requirements
 
 - Node.js 18+
-- npm or yarn
-- For iOS builds: Xcode (local) or cloud instance with macOS
-- For Android builds: Android SDK (local) or cloud instance
+- For iOS builds: Xcode (local builds) or cloud build subscription
+- For Android builds: Android SDK (local builds) or cloud build subscription
 
 ## License