ota-cli-mac 🛠

The official command-line powerhouse for the OTA Platform. This tool handles the heavy lifting of building, diffing, and deploying React Native updates with a focus on speed, security, and developer experience.

⚡️ Overview

ota-cli-mac is more than just an uploader. It is an intelligent deployment engine that understands your React Native project structure. It automatically handles environment detection, native versioning, and smart asset diffing to ensure your users get the smallest possible update as quickly as possible.

🚀 Installation & Quick Start

You can run the CLI without installing it globally using npx:

npx --package ota-cli-mac ota release-react \
  --appId <YOUR_APP_UUID> \
  --platform android \
  --apiKey <YOUR_API_KEY>

📖 The release-react Pipeline

When you run release-react, the CLI executes a strictly ordered 10-step pipeline:

1. Bootstrap: Fetches AWS/S3 credentials and bucket configuration from your OTA server.
2. Git Check: Verifies repository status and captures the current Commit SHA to use as a unique updateId.
3. Build: Runs react-native bundle. For Android, it automatically attempts to compile the bundle into Hermes Bytecode (.hbc).
4. Version Detection: Scans build.gradle or Info.plist to detect the native app version.
5. Smart Diff: Fetches the previous release manifest and compares it to the new build.
6. CAS Processing: Identifies only the files that have changed (Content Addressable Storage).
7. Manifest Signing: (Optional) Signs the update manifest using your RSA private key.
8. Finalize URLs: Maps all files to your CDN endpoints.
9. Parallel Upload: Uploads only the changed files to S3 with optimized concurrency.
10. Registration: Notifies the OTA backend that the new release is live.

⚙️ Configuration & Options

Core Options

| Option | Alias | Description | | :--- | :--- | :--- | | --appId | -a | Required. Your App UUID from the Admin Panel. | | --apiKey | -k | Required. API Key for auth and bootstrapping. | | --platform | -p | Required. android or ios. | | --deployment| -d | Target channel: production (default), staging, or beta. |

Behavior Options

| Option | Default | Description | | :--- | :--- | :--- | | --mandatory | false | If true, the SDK will force the update on the user. | | --installMode| nextRestart | When to apply: nextRestart, immediate, or nextResume. | | --changelog | "" | Release notes for this update. | | --updateId | (Git SHA) | Manual override for the update identifier. |

Build & Performance

| Option | Default | Description | | :--- | :--- | :--- | | --entryFile | index.js | The entry point for your React Native app. | | --outDir | out | Temporary directory for build artifacts. | | --parallel | true | Enables high-speed parallel file uploads. | | --concurrency| 5 | Number of simultaneous upload workers. |

🎯 Advanced Targeting

You can restrict an update to specific native versions of your app:

• Exact Version: ota release-react ... --targetingType EXACT --targetAppVersion "1.2.5"
• Version Range: ota release-react ... --targetingType RANGE --targetAppVersion ">=1.1.0 <1.3.0"
• Version List: ota release-react ... --targetingType LIST --targetAppVersion "1.0.1,1.0.3"

🧠 Smart Features

1. Automatic Native Versioning

The CLI is "Native Aware." You don't need to tell it which version of your app you are targeting. It will:

• Android: Read versionName from android/app/build.gradle or build.gradle.kts.
• iOS: Read CFBundleShortVersionString from the Info.plist in your ios/ subdirectories.

2. Hermes Bytecode (Android)

The CLI automatically searches for the hermesc compiler in your node_modules. If found, it will compile your JS bundle into bytecode.

• Why? Bytecode results in smaller updates and significantly faster app startup times.
• Fallback: If hermesc isn't found, the CLI safely falls back to a standard JS bundle.

3. Git-Integrated Safety

By default, the CLI uses your current Git commit as the version marker. It will also warn you if you have uncommitted changes to prevent "dirty" releases from being deployed to users.

🛡 Security: Manifest Signing

For high-security environments, you can sign your manifests to prevent tampering. Provide a PEM private key:

ota release-react ... --privateKey ./keys/ota-private.pem --kid production-v1

📄 License

MIT