rock CLI
The Rock CLI is a command-line tool that helps you develop, build, and run React Native applications.
Basic usage:
Global Options
The following options are available for all commands:
| Options | Description |
|---|---|
-h or --help | Shows all available options |
-V or --version | Outputs the Rock version number |
--verbose | Sets verbose logging |
Available Commands
Rock CLI uses a modular design where available commands depend on your configuration. The following commands are available by default for all configurations (these are internal commands that you typically won't need to run):
| Command | Description |
|---|---|
config | Outputs autolinking config (from Community CLI) |
fingerprint | Calculates fingerprint for project or platform |
clean | Cleans various caches to free up disk space |
help | Displays help menu for a command |
remote-cache | Manage remote cache |
Additional commands for development, building, and running apps are provided by specialized plugins.
Bundler Plugins
Bundler plugins are configured through the bundler property in your configuration. Available bundlers include:
-
@rock-js/plugin-metro– Metro bundler plugin with the following commands:Command Description startStarts Metro dev server bundleBundles JavaScript with Metro -
@rock-js/plugin-repack– Re.Pack bundler plugin with the following commands:Command Description startStarts Re.Pack dev server bundleBundles JavaScript with Re.Pack
Platform Plugins
Platform plugins are configured through the platform property in your configuration. Available platforms include:
-
@rock-js/platform-android– Android platform plugin with the following commands:Command Description run:androidRuns Android app on emulator or device build:androidBuilds Android app for generic emulator, device or distribution sign:androidSigns Android app with keystore -
@rock-js/platform-ios– iOS platform plugin with the following commands:Command Description build:iosBuilds iOS app for generic simulator, device or distribution run:iosRuns iOS app on simulator or device sign:iosSigns iOS app with certificate and provisioning profile
Command Options
rock start Options
The start command launches a development server (either Re.Pack or Metro, depending on your bundler plugin) that connects to your apps through port 8081 by default. It provides features like Hot Module Reloading (HMR) and error reporting.
| Option | Description |
|---|---|
--port <number> | Port to run the server on (default: 8081) |
--host <string> | Host to run the server on (default: "") |
--project-root <path>, --projectRoot <path> | Path to a custom project root |
--watch-folders <list>, --watchFolders <list> | Specify any additional folders to be added to the watch list |
--asset-plugins <list>, --assetPlugins <list> | Specify any additional asset plugins to be used by the packager by full filepath |
--source-exts <list>,--sourceExts <list> | Specify any additional source extensions to be used by the packager |
--max-workers <number> | Specifies the maximum number of workers the worker-pool will spawn for transforming files |
--transformer <string> | Specify a custom transformer to be used |
--reset-cache, --resetCache | Removes cached files |
--custom-log-reporter-path <string> | Path to a JavaScript file that exports a log reporter as a replacement for TerminalReporter |
--https | Enables https connections to the server |
--key <path> | Path to custom SSL key |
--cert <path> | Path to custom SSL cert |
--config <string> | Path to the CLI configuration file |
--no-interactive | Disables interactive mode |
--client-logs | [Deprecated] Enable plain text JavaScript log streaming for all connected apps |
rock bundle Options
The bundle command creates an optimized JavaScript bundle for your application, optionally using Hermes bytecode.
| Option | Description |
|---|---|
--entry-file <path> | Path to the root JS file, either absolute or relative to JS root |
--platform <string> | Either "ios" or "android" (default: "ios") |
--transformer <string> | Specify a custom transformer to be used |
--dev [boolean] | If false, warnings are disabled and the bundle is minified (default: true) |
--minify [boolean] | Allows overriding whether bundle is minified. Defaults to false if dev is true, true if dev is false |
--bundle-output <string> | File name where to store the resulting bundle, ex. /tmp/groups.bundle |
--bundle-encoding <string> | Encoding the bundle should be written in (default: "utf8") |
--max-workers <number> | Specifies the maximum number of workers the worker-pool will spawn for transforming files |
--sourcemap-output <string> | File name where to store the sourcemap file for resulting bundle, ex. /tmp/groups.map |
--sourcemap-sources-root <string> | Path to make sourcemap's sources entries relative to, ex. /root/dir |
--sourcemap-use-absolute-path | Report SourceMapURL using its full path (default: false) |
--assets-dest <string> | Directory name where to store assets referenced in the bundle |
--unstable-transform-profile <string> | Experimental, transform JS for a specific JS engine (default: "default") |
--asset-catalog-dest [string] | Path where to create an iOS Asset Catalog for images |
--reset-cache | Removes cached files (default: false) |
--read-global-cache | Try to fetch transformed JS code from the global cache, if configured (default: false) |
--config <string> | Path to the CLI configuration file |
--resolver-option <string...> | Custom resolver options of the form key=value. URL-encoded. May be specified multiple times |
--config-cmd [string] | [Internal] A hack for Xcode build script pointing to wrong bundle command |
--hermes | Passes the output JS bundle to Hermes compiler and outputs a bytecode file |
rock build:ios Options
The build:ios command builds your iOS app for simulators, devices, or distribution, producing either an APP directory (for simulators) or an IPA file (for devices and distribution).
| Option | Description |
|---|---|
--configuration <string> | Xcode scheme configuration (case sensitive) |
--scheme <string> | Xcode scheme to use |
--target <string> | Xcode target to use |
--extra-params <string> | Custom xcodebuild parameters |
--export-extra-params <string> | Custom xcodebuild export archive parameters |
--export-options-plist <string> | Export options file for archiving (default: ExportOptions.plist) |
--build-folder <string> | Location for iOS build artifacts |
--destination <strings...> | Define destination(s) for the build. You can pass multiple destinations as separate values or repeated use of the flag. Values can be either: "simulator", "device" or destinations supported by "xcodebuild -destination" flag, e.g. "generic/platform=iOS" |
--archive | Create Xcode archive (IPA) |
--no-install-pods | Skip CocoaPods installation |
--no-new-arch | Build in legacy async architecture |
rock run:ios Options
The run:ios command runs your iOS app on a simulator or device. It follows this build strategy:
- Use the provided binary if specified with
--binary-path - Build locally if
--localflag is set - Otherwise, try to use a cached build from cache (in
.rockfolder)
The build cache is populated either by a local build or when downloaded frome remote storage with remoteCacheProvider.
run:ios extends the functionality of build:ios with additional runtime options.
| Option | Description |
|---|---|
--port <number> | Bundler port (default: 8081) |
--binary-path <string> | Path to pre-built .app binary |
--device <string> | Device/simulator to use (by name or UDID) |
--catalyst | Run on Mac Catalyst |
--local | Force local build with xcodebuild |
rock sign:ios Options
The sign:ios command either signs your iOS app with certificates and provisioning profiles, producing a signed IPA file ready for distribution, or modifies APP file without signing. It allows for replacing the JS bundle with a new version.
| Argument | Description |
|---|---|
binaryPath | Path to the IPA or APP file |
| Option | Description |
|---|---|
--app | Modify APP file (directory) instead of IPA file. No signing is done |
--identity <string> | Certificate Identity name for code signing |
--output <string> | Path to output IPA file |
--build-jsbundle | Build JS bundle before signing |
--jsbundle <string> | Path to JS bundle to apply before signing |
--no-hermes | Don't use Hermes for JS bundle |
rock build:android Options
The build:android command builds your Android app for emulators, devices, or distribution, producing either APK or AAB files. It follows this build strategy:
- Use the provided binary if specified with
--binary-path - Build locally if
--localflag is set - Otherwise, try to use a cached build from cache (in
.rockfolder)
The build cache is populated either by a local build or when downloaded frome remote storage with remoteCacheProvider.
| Option | Description |
|---|---|
--variant <string> | Build variant (debug/release) |
--aab | Build Android App Bundle instead of APK |
--active-arch-only | Build only for active architecture |
--tasks <array> | Custom Gradle tasks |
--extra-params <array> | Extra parameters for Gradle |
rock run:android Options
The run:android command runs your Android app on an emulator or device. It extends the functionality of build:android with additional runtime options.
Same as for build:android and:
| Option | Description |
|---|---|
--app-id <string> | Application ID |
--app-id-suffix <string> | Application ID suffix |
--binary-path <string> | Path to pre-built APK |
--local | Force local build with Gradle wrapper |
rock sign:android Options
The sign:android <binaryPath> command signs your Android app with a keystore, producing a signed APK file ready for distribution. It allows for replacing the JS bundle with a new version.
| Argument | Description |
|---|---|
binaryPath | Path to the APK file |
| Option | Description |
|---|---|
--keystore <string> | Path to keystore file |
--keystore-password <string> | Password for keystore file |
--output <string> | Path to output APK file |
--build-jsbundle | Build JS bundle before signing |
--jsbundle <string> | Path to JS bundle to apply before signing |
--no-hermes | Don't use Hermes for JS bundle |
rock clean Options
The clean command helps you free up disk space by removing various caches and temporary files from your React Native project. It can clean Android (Gradle), iOS (CocoaPods), Metro, Watchman, Rock's own project caches, and package manager caches.
| Option | Description |
|---|---|
--include <string> | Comma-separated list of caches to clean. Available options: android, gradle, cocoapods, metro, watchman, npm, yarn, bun, pnpm, rock |
--verify-cache | Whether to verify the cache (currently only applies to npm cache) |
--all | Clean all available caches without interactive prompt |
rock remote-cache Actions and Options
The remote-cache <action> command provides utilities to interact with the remote build cache configured via your remoteCacheProvider. This is useful for inspecting, downloading, uploading, or deleting build artifacts stored remotely.
Available actions:
| Action | Description |
|---|---|
list | Lists the latest artifact matching the specified criteria |
list-all | Lists all artifacts (optionally filtered by platform and traits) |
download | Downloads an artifact from remote cache to local cache |
upload | Uploads a binary to remote cache. Accepts --ad-hoc flag for Ad-Hoc distritbuion |
delete | Deletes artifacts from remote cache |
get-provider-name | Returns the name of the configured remote cache provider |
Actions have different options available:
| Option | Description |
|---|---|
--json | Output results in JSON format instead of human-readable format |
--name <string> | Full artifact name to operate on. Cannot be used with --platform or --traits |
--all | List or delete all matching artifacts (affects list and delete actions only) |
--all-but-latest | Delete all but the latest matching artifact (affects delete action only) |
-p, --platform <string> | Platform to target (ios or android). Must be used with --traits |
-t, --traits <list> | Comma-separated traits that construct the final artifact name. For Android: variant (e.g., debug, release). For iOS: destination and configuration (e.g., simulator,Release) |
--binary-path <string> | Path to the binary to upload (used with upload action) |
--ad-hoc <string> | Upload IPA for ad-hoc distribution and installation from URL. Additionally uploads index.html and manifest.plist' |
For example, to download remote cache for iOS simulator with Release configuration, you can use remote-cache download with --name option
or pass --traits, so you don't need to pass the fingerprint:
Ad-hoc distribution
Ad-hoc distribution allows you to share your iOS app with testers without going through the App Store. Testers can install your app directly on their devices by visiting a web page and tapping "Install App".
What is Ad-hoc distribution?
Ad-hoc distribution is a method for sharing iOS apps with testers without going through the App Store. It requires devices to be registered in your Apple Developer account and is perfect for beta testing, internal testing, or client demos. Apps installed this way will appear on the device's home screen just like any other app.
How it works:
- Build your app with a valid provisioning profile that includes your testers' devices
- Use
upload --ad-hocto upload the app for ad-hoc distribution - Share the generated URL with your testers
- Testers visit the URL and tap "Install App" to install directly on their device
The command creates a special folder structure that includes:
- Your signed IPA file
- An HTML page for easy installation (you need to configure your provider to make this file publicly available)
- A manifest file that iOS uses to install the app
The folder will be available at ad-hoc/ directory of your configured remote cache provider.