AppsOnAir CodePush CLI

The AppsOnAir-CodePush CLI is a Node.js application that allows users to interact with AppsOnAir CodePush service.

---

CLI Installation

Run the following command to install @appsonair/codepush-cli globally:

NPM

Terminal

npm install -g @appsonair/codepush-cli

Yarn

Terminal

yarn global add @appsonair/codepush-cli

---

Usage

After installing AppsOnAirCodePush CLI globally, it will be available under appsonair-codepush.

---

Account Management

Before you can begin releasing app updates, you need to create a AppsOnAir account. You can do this by simply running the following command once you've installed the CLI:

Terminal

appsonair-codepush register

This will launch a browser, asking you to authenticate with your AppsOnAir account. Once authenticated, it generate an access key you can copy/paste into the CLI in order to login.

note

After registering, you are automatically logged-in with the CLI, so until you explicitly log out, you don't need to login again from the same machine.

Authentication

Most commands within the AppsOnAirCodePush CLI require authentication, and therefore, before you can begin managing your account, you need to login using the AppsOnAir account you used when registering. You can do this by running the following command:

Terminal

appsonair-codepush login

This will launch a browser, asking you to authenticate with your AppsOnAir account. This will generate an access key that you need to copy/paste into the CLI (it will prompt you for it). You are now successfully authenticated and can safely close your browser window.

If at any time you want to determine if you're already logged in, you can run the following command to display the e-mail address associated with your current authentication session, which identity providers your account is linked to AppsOnAir:

Terminal

appsonair-codepush whoami

When you login from the CLI, your access key is persisted to disk for the duration of your session so that you don't have to login every time you attempt to access your account. In order to end your session and delete this access key, simply run the following command:

Terminal

appsonair-codepush logout

---

App Management

If you want to list all apps that you've registered with the AppsOnAirCodePush, you can run the following command:

Terminal

appsonair-codepush app ls

App Collaboration

If at any time you want to list all collaborators that have been added to an app, you can simply run the following command:

Terminal

appsonair-codepush collaborator ls <appName>

Deployment Management

From the AppsOnAirCodePush perspective, an app is simply a named grouping for one or more things called "deployments". While the app represents a conceptual "namespace" or "scope" for a platform-specific version of an app (e.g. the iOS port of Foo app), its deployments represent the actual target for releasing updates (for developers) and synchronizing updates (for end-users).

note

As you'll see below, the release and rollback commands require both an app name and a deployment name is order to work, because it is the combination of the two that uniquely identifies a point of distribution (e.g. I want to release an update of my iOS app to my beta testers).

Whenever an app is registered with the AppsOnAirCodePush service, it includes deployments by default: Production. This allows you to immediately begin releasing updates to an internal environment, where you can thoroughly test each update before pushing them out to your end-users. This workflow is critical for ensuring your releases are ready for mass-consumption, and is a practice that has been established in the web for a long time.

If at any time you'd like to view the list of deployments that a specific app includes, you can simply run the following command:

Terminal

appsonair-codepush deployment ls <appName> [--displayKeys|-k]

This will display not only the list of deployments, but also the update metadata (e.g. mandatory, description) and installation metrics for their latest release:

note

Due to their infrequent use and needed screen real estate, deployment keys aren't displayed by default. If you need to view them, simply make sure to pass the -k flag to the deployment ls command.

The install metrics have the following meaning:

• Active - The number of successful installs that are currently running this release (i.e. if the user opened your app, they would see/run this version). This number will increase and decrease as end-users upgrade to and away from this release, respectively. This metric shows both the total of active users, as well as what percentage of your overall audience that represents. This makes it easy to determine the distribution of updates that your users are currently running, as well as answer questions such as "How many of my users have received my latest update?".

• Total - The total number of successful installations that this update has received overall. This number only ever increases as new users/devices install it, and therefore, this is always a superset of the total active count. An update is considered successful once notifyApplicationReady (or sync) is called after it was installed. Between the moment that an update is downloaded, and it is marked as being successful, it will be reported as a "pending" update (see below for details).

• Pending - The number of times this release has been downloaded, but not yet installed (i.e. the app was restarted to apply the changes). Therefore, this metric increases as updates are downloaded, and decreases as those corresponding downloaded updates are installed. This metric primarily applies to updates that aren't configured to install immediately, and helps provide the broader picture of release adoption for apps that rely on app resume and/or restart to apply an update (e.g. I want to rollback an update and I'm curious if anyone has downloaded it yet). If you've configured updates to install immediately, and are still seeing pending updates being reported, then it's likely that you're not calling notifyApplicationReady (or sync) on app start, which is the method that initiates sending install reports and marks installed updates as being considered successful.

• Rollbacks - The number of times that this release has been automatically rolled back on the client. Ideally this number should be zero, and in that case, this metric isn't even shown. However, if you released an update that includes a crash as part of the installation process, the AppsOnAirCodePush plugin will roll the end-user back to the previous release, and report that issue back to the server. This allows your end-users to remain unblocked in the event of broken releases, and by being able to see this telemetry in the CLI, you can identify erroneous releases and respond to them by rolling it back on the server.

• Rollout - Indicates the percentage of users that are eligible to receive this update. This property will only be displayed for releases that represent an "active" rollout, and therefore, have a rollout percentage that is less than 100%. Additionally, since a deployment can only have one active rollout at any given time, this label would only be present on the latest release within a deployment.

• Disabled - Indicates whether the release has been marked as disabled or not, and therefore, is downloadable by end users. This property will only be displayed for releases that are actually disabled.

When the metrics cell reports No installs recorded, that indicates that the server hasn't seen any activity for this release. This could either be because it precluded the plugin versions that included telemetry support, or no end-users have synchronized with the AppsOnAirCodePush server yet. As soon as an install happens, you will begin to see metrics populate in the CLI for the release.

---

Releasing Updates

Once your app has been configured to query for updates against the AppsOnAirCodePush server, you can begin releasing updates to it. In order to provide both simplicity and flexibility, the AppsOnAirCodePush CLI includes two different commands for releasing updates:

1. General - Releases an update to the AppsOnAirCodePush server that was generated by an external tool or build script (e.g. a Gulp task, the react-native bundle command). This provides the most flexibility in terms of fitting into existing workflows, since it strictly deals with AppsOnAirCodePush-specific step, and leaves the app-specific compilation process to you.

2. React Native - Performs the same functionality as the general release command, but also handles the task of generating the updated app contents for you (JS bundle and assets), instead of requiring you to run both react-native bundle and then appsonair-codepush release.

Which of these commands you should use is mostly a matter of requirements and/or preference. However, we generally recommend using the platform-specific command to start (since it greatly simplifies the experience), and then leverage the general-purpose release command if/when greater control is needed.

Releasing Updates (General)

Terminal

appsonair-codepush release <appName> <updateContents> <targetBinaryVersion>
[--description <description>]
[--disabled <disabled>]
[--mandatory]
[--noDuplicateReleaseError]
[--rollout <rolloutPercentage>]

App name parameter

This specifies the name of the AppsOnAirCodePush app that this update is being released for. If you need to look it up, you can run the appsonair-codepush app ls command to see your list of apps.

Update contents parameter

This specifies the location of the updated app code and assets you want to release. You can provide either a single file (e.g. a JS bundle for a React Native app), or a path to a directory. Note that you don't need to ZIP up multiple files or directories in order to deploy those changes, since the CLI will automatically ZIP them for you.

It's important that the path you specify refers to the platform-specific, prepared/bundled version of your app. The following table outlines which command you should run before releasing, as well as the location you can subsequently refer to using the updateContents parameter:

Platform	Prepare command	Package path (relative to project root)
React Native wo/assets (Android)	react-native bundle --platform android --entry-file <entryFile> --bundle-output <bundleOutput> --dev false	Value of the --bundle-output option
React Native w/assets (Android)	react-native bundle --platform android --entry-file <entryFile> --bundle-output <releaseFolder>/<bundleOutput> --assets-dest <releaseFolder> --dev false	Value of the --assets-dest option, which should represent a newly created directory that includes your assets and JS bundle
React Native wo/assets (iOS)	react-native bundle --platform ios --entry-file <entryFile> --bundle-output <bundleOutput> --dev false	Value of the --bundle-output option
React Native w/assets (iOS)	react-native bundle --platform ios --entry-file <entryFile> --bundle-output <releaseFolder>/<bundleOutput> --assets-dest <releaseFolder> --dev false	Value of the --assets-dest option, which should represent a newly created directory that includes your assets and JS bundle

Target binary version parameter

This specifies the store/binary version of the application you are releasing the update for, so that only users running that version will receive the update, while users running an older and/or newer version of the app binary will not. This is useful for the following reasons:

1. If a user is running an older binary version, it's possible that there are breaking changes in the AppsOnAirCodePush update that wouldn't be compatible with what they're running.

2. If a user is running a newer binary version, then it's presumed that what they are running is newer (and potentially incompatible) with the AppsOnAirCodePush update.

If you ever want an update to target multiple versions of the app store binary, we also allow you to specify the parameter as a semver range expression. That way, any client device running a version of the binary that satisfies the range expression (i.e. semver.satisfies(version, range) returns true) will get the update. Examples of valid semver range expressions are as follows:

Range Expression	Who gets the update
1.2.3	Only devices running the specific binary app store version 1.2.3 of your app
*	Any device configured to consume updates from your AppsOnAirCodePush app
1.2.x	Devices running major version 1, minor version 2 and any patch version of your app
1.2.3 - 1.2.7	Devices running any binary version between 1.2.3 (inclusive) and 1.2.7 (inclusive)
>=1.2.3 <1.2.7	Devices running any binary version between 1.2.3 (inclusive) and 1.2.7 (exclusive)
~1.2.3	Equivalent to >=1.2.3 <1.3.0
^1.2.3	Equivalent to >=1.2.3 <2.0.0

note

If your semver expression starts with a special shell character or operator such as >, ^, or , the command may not execute correctly if you do not wrap the value in quotes as the shell will not supply the right values to our CLI process. Therefore, it is best to wrap your targetBinaryVersion parameter in double quotes when calling the release command, e.g. appsonair-codepush release MyApp-iOS updateContents ">1.2.3".

note

As defined in the semver spec, ranges only work for non pre-release versions: https://github.com/npm/node-semver#prerelease-tags. If you want to update a version with pre-release tags, then you need to write the exact version you want to update (1.2.3-beta for example).

The following table outlines the version value that AppsOnAirCodePush expects your update's semver range to satisfy for each respective app type:

Platform	Source of app store version
React Native (Android)	The android.defaultConfig.versionName property in your build.gradle file
React Native (iOS)	The CFBundleShortVersionString key in the Info.plist file

note

If the app store version in the metadata files are missing a patch version, e.g. 2.0, it will be treated as having a patch version of 0, i.e. 2.0 -> 2.0.0

Description parameter

This provides an optional "change log" for the deployment. The value is simply round tripped to the client so that when the update is detected, your app can choose to display it to the end-user (e.g. via a "What's new?" dialog). This string accepts control characters such as \n and \t so that you can include whitespace formatting within your descriptions for improved readability.

note

This parameter can be set using either "--description" or "-des"

Disabled parameter

This specifies whether an update should be downloadable by end users or not. If left unspecified, the update will not be disabled (i.e. users will download it the moment your app calls sync). This parameter can be valuable if you want to release an update that isn't immediately available, until you explicitly patch it when you want end users to be able to download it (e.g. an announcement blog post went live).

note

This parameter can be set using either "--disabled" or "-x"

Mandatory parameter

This specifies whether the update should be considered mandatory or not (e.g. it includes a critical security fix). This attribute is simply round tripped to the client, who can then decide if and how they would like to enforce it.

note

This parameter is simply a "flag", and therefore, its absence indicates that the release is optional, and its presence indicates that it's mandatory. You can provide a value to it (e.g. --mandatory true), however, simply specifying --mandatory is sufficient for marking a release as mandatory.

The mandatory attribute is unique because the server will dynamically modify it as necessary in order to ensure that the semantics of your releases are maintained for your end-users. For example, imagine that you released the following three updates to your app:

Release	Mandatory?
v1	No
v2	Yes
v3	No

If an end-user is currently running v1, and they query the server for an update, it will respond with v3 (since that is the latest), but it will dynamically convert the release to mandatory, since a mandatory update was released in between. This behavior is important since the code contained in v3 is incremental to that included in v2, and therefore, whatever made v2 mandatory, continues to make v3 mandatory for anyone that didn't already acquire v2.

If an end-user is currently running v2, and they query the server for an update, it will respond with v3, but leave the release as optional. This is because they already received the mandatory update, and therefore, there isn't a need to modify the policy of v3. This behavior is why we say that the server will "dynamically convert" the mandatory flag, because as far as the release goes, its mandatory attribute will always be stored using the value you specified when releasing it. It is only changed on-the-fly as necessary when responding to an update check from an end-user.

If you never release an update that is marked as mandatory, then the above behavior doesn't apply to you, since the server will never change an optional release to mandatory unless there were intermingled mandatory updates as illustrated above. Additionally, if a release is marked as mandatory, it will never be converted to optional, since that wouldn't make any sense. The server will only change an optional release to mandatory in order to respect the semantics described above.

note

This parameter can be set using either --mandatory or -m

No duplicate release error parameter

This specifies that if the update is identical to the latest release on the deployment, the CLI should generate a warning instead of an error. This is useful for continuous integration scenarios where it is expected that small modifications may trigger releases where no production code has changed.

Rollout parameter

IMPORTANT: In order for this parameter to actually take affect, your end users need to be running version 1.9.0-beta+ (for React Native) of the AppsOnAirCodePush plugin. If you release an update that specifies a rollout property, no end user running an older version of React Native plugins will be eligible for the update. Therefore, until you have adopted the necessary version of the platform-specific AppsOnAirCodePush plugin (as previously mentioned), we would advise not setting a rollout value on your releases, since no one would end up receiving it.

This specifies the percentage of users (as an integer between 1 and 100) that should be eligible to receive this update. It can be helpful if you want to "flight" new releases with a portion of your audience (e.g. 25%), and get feedback and/or watch for exceptions/crashes, before making it broadly available for everyone. If this parameter isn't set, it is set to 100%, and therefore, you only need to set it if you want to actually limit how many users will receive it.

When leveraging the rollout capability, there are a few additional considerations to keep in mind:

1. You cannot release a new update to a deployment whose latest release is an "active" rollout (i.e. its rollout property is non-null). The rollout needs to be "completed" (i.e. setting the rollout property to 100) before you can release further updates to the deployment.

2. If you rollback a deployment whose latest release is an "active" rollout, the rollout value will be cleared, effectively "deactivating" the rollout behavior

note

This parameter can be set using either --rollout or -r

Releasing Updates (React Native)

Terminal

appsonair-codepush release-react <appName>
[--bundleName <bundleName>]
[--description <description>]
[--development <development>]
[--disabled <disabled>]
[--entryFile <entryFile>]
[--gradleFile <gradleFile>]
[--mandatory]
[--noDuplicateReleaseError]
[--outputDir <outputDir>]
[--plistFile <plistFile>]
[--plistFilePrefix <plistFilePrefix>]
[--sourcemapOutput <sourcemapOutput>]
[--targetBinaryVersion <targetBinaryVersion>]
[--rollout <rolloutPercentage>]
[--useHermes <useHermes>]
[--podFile <podFile>]
[--extraHermesFlags <extraHermesFlags>]
[--privateKeyPath <privateKeyPath>]
[--xcodeProjectFile <xcodeProjectFile>]
[--xcodeTargetName <xcodeTargetName>]
[--buildConfigurationName <buildConfigurationName>]

The release-react command is a React Native-specific version of the "vanilla" release command, which supports all of the same parameters (e.g. --mandatory, --description), yet simplifies the process of releasing updates by performing the following additional behavior:

1. Running the react-native bundle command in order to generate the update contents (JS bundle and assets) that will be released to the AppsOnAirCodePush server. It uses sensible defaults as much as possible (e.g. creating a non-dev build, assuming an iOS entry file is named index.ios.js), but also exposes the relevant react-native bundle parameters to enable flexibility (e.g. --sourcemapOutput).

2. Inferring the targetBinaryVersion of this release by using the version name that is specified in your project's Info.plist (for iOS) and build.gradle (for Android) files.

To illustrate the difference that the release-react command can make, the following is an example of how you might generate and release an update for a React Native app using the "vanilla" release command:

Terminal

mkdir ./AppsOnAirCodePush

react-native bundle --platform ios \
--entry-file index.ios.js \
--bundle-output ./AppsOnAirCodePush/main.jsbundle \
--assets-dest ./AppsOnAirCodePush \
--dev false

appsonair-codepush release MyApp-iOS ./AppsOnAirCodePush 1.0.0

Achieving the equivalent behavior with the release-react command would simply require the following command, which is generally less error-prone:

Terminal

appsonair-codepush release-react MyApp-iOS

App name parameter

This is the same parameter as the one described in the above section.

Description parameter

This is the same parameter as the one described in the above section.

Mandatory parameter

This is the same parameter as the one described in the above section.

No duplicate release error parameter

This is the same parameter as the one described in the above section.

Rollout parameter

This is the same parameter as the one described in the above section. If left unspecified, the release will be made available to all users.

Target binary version parameter

This is the same parameter as the one described in the above section. If left unspecified, this defaults to targeting the exact version specified in the app's Info.plist (for iOS) and build.gradle (for Android) files.

Bundle name parameter

This specifies the file name that should be used for the generated JS bundle. If left unspecified, the standard bundle name will be used for the specified platform: main.jsbundle (iOS) and index.android.bundle (Android).

note

This parameter can be set using either --bundleName or -b

Development parameter

This specifies whether to generate a unminified, development JS bundle. If left unspecified, this defaults to false where warnings are disabled and the bundle is minified.

note

This parameter can be set using either --development or --dev

Disabled parameter

This is the same parameter as the one described in the above section.

Entry file parameter

This specifies the relative path to the app's root/entry JavaScript file. If left unspecified, this defaults to index.ios.js (for iOS) or index.android.js (for Android) if that file exists, or index.js otherwise.

note

This parameter can be set using either --entryFile or -e

Gradle file parameter (Android only)

This specifies the relative path to the build.gradle file that the CLI should use when attempting to auto-detect the target binary version for the release. This parameter is only meant for advanced scenarios, since the CLI will automatically be able to find your build.grade file in "standard" React Native projects. However, if your gradle file is located in an arbitrary location, that the CLI can't discover, then using this parameter allows you to continue releasing AppsOnAirCodePush updates, without needing to explicitly set the --targetBinaryVersion parameter. Since build.gradle is a required file name, specifying the path to the containing folder or the full path to the file itself will both achieve the same effect.

Terminal

appsonair-codepush release-react MyApp-Android -p "./foo/bar/"
appsonair-codepush release-react MyApp-Android -p "./foo/bar/build.gradle"

Plist file parameter (iOS only)

This specifies the relative path to the Info.plist file that the CLI should use when attempting to auto-detect the target binary version for the release. This parameter is only meant for advanced scenarios, since the CLI will automatically be able to find your Info.plist file in "standard" React Native projects, and you can use the --plistFilePrefix parameter in order to support per-environment plist files. However, if your plist is located in an arbitrary location, that the CLI can't discover, then using this parameter allows you to continue releasing AppsOnAirCodePush updates, without needing to explicitly set the --targetBinaryVersion parameter.

Terminal

appsonair-codepush release-react MyApp-iOS -p "./foo/bar/MyFile.plist"

note

This parameter can be set using either --plistFile or -p

Plist file prefix parameter (iOS only)

This specifies the file name prefix of the Info.plist file that that CLI should use when attempting to auto-detect the target binary version for the release. This can be useful if you want to be able to release AppsOnAirCodePush updates without needing to explicitly set the --targetBinaryVersion parameter. By specifying a --plistFilePrefx, the CLI will look for a file named <prefix>-Info.plist, instead of simply Info.plist (which is the default behavior), in the following locations: ./ios and ./ios/<appName>. If your plist file isn't located in either of those directories (e.g. your app is a native iOS app with embedded RN views), or uses an entirely different file naming convention, then consider using the --plistFile parameter.

Terminal

# Auto-detect the target binary version of this release by looking up the
# app version within the PRODUCTION-Info.plist file in either the ./ios or ./ios/<APP> directories.
appsonair-codepush release-react MyApp-iOS --pre "PRODUCTION"

note

This parameter can be set using either --plistFilePrefix or --pre

Sourcemap output parameter

This specifies the relative path to where the generated JS bundle's sourcemap file should be written. If left unspecified, sourcemaps will not be generated.

note

This parameter can be set using either --sourcemapOutput or -s

Output directory parameter

This specifies the relative path to where the assets, JS bundle and sourcemap files should be written. If left unspecified, the assets, JS bundle and sourcemap will be copied to the /tmp/AppsOnAirCodePush folder.

note

This parameter can be set using either --outputDir or -o

Use Hermes parameter

This parameter enforces the use of the Hermes compiler. If not specified, the automatic checks will be performed, inspecting the build.gradle and Podfile for the Hermes flag.

note

This parameter can be set using either --hermesEnabled or -h

Podfile parameter (iOS only)

The Podfile path will be used for Hermes automatic check. Not used if --useHermes is specified.

note

This parameter can be set using either --podfile or -pod

Extra hermes flags parameter

Hermes flags which will be passed to Hermes compiler.

note

This parameter can be set using either --extraHermesFlags or -hf

Private key path parameter

Private key path which is used for code signing.

note

This parameter can be set using either --privateKeyPath or -k

Xcode project file parameter

Path to the Xcode project or project.pbxproj file.

note

This parameter can be set using either --xcodeProjectFile or -xp

Xcode target name parameter

Name of target (PBXNativeTarget) which specifies the binary version you want to target this release at (iOS only).

note

This parameter can be set using either --xcodeTargetName or -xt

Build configuration name parameter

Name of build configuration which specifies the binary version you want to target this release at. For example, 'Debug' or 'Release' (iOS only).

note

This parameter can be set using either --buildConfigurationName or -c

---

Debugging AppsOnAirCodePush Integration

Once you've released an update, React Native plugin has been integrated into your app, it can be helpful to diagnose how the plugin is behaving, especially if you run into an issue and want to understand why. In order to debug the AppsOnAirCodePush update discovery experience, you can run the following command in order to easily view the diagnostic logs produced by the AppsOnAirCodePush plugin within your app:

Terminal

appsonair-codepush debug <platform>

# View all AppsOnAirCodePush logs from a running
# instance of the iOS simulator.
appsonair-codepush debug ios

# View all AppsOnAirCodePush logs from a running
# Android emulator or attached device.
appsonair-codepush debug android

Under the covers, this command simply automates the usage of the iOS system logs and ADB logcat, but provides a platform-agnostic, filtered view of all logs coming from the AppsOnAirCodePush plugin. This way, you don't need to learn and/or use another tool simply to be able to answer basic questions about how AppsOnAirCodePush is behaving.

note

The debug command supports both emulators and devices for Android, but currently only supports listening to logs from the iOS simulator. We hope to add device support soon.

---

Patching Update Metadata

After releasing an update, there may be scenarios where you need to modify one or more of the metadata attributes associated with it (e.g. you forgot to mark a critical bug fix as mandatory, you want to increase the rollout percentage of an update). You can easily do this by running the following command:

Terminal

appsonair-codepush patch <appName>
[--label <releaseLabel>]
[--mandatory <isMandatory>]
[--description <description>]
[--rollout <rolloutPercentage>]
[--disabled <isDisabled>]
[--targetBinaryVersion <targetBinaryVersion>]

note

This command doesn't allow modifying the actual update contents of a release. If you need to respond to a release that has been identified as being broken, you should use the rollback command to immediately roll it back, and then if necessary, release a new update with the appropriate fix when it is available.

Aside from the appName, all parameters are optional, and therefore, you can use this command to update just a single attribute or all of them at once. Calling the patch command without specifying any attribute flag will result in a no-op.

Terminal

# Mark the latest production release as mandatory
appsonair-codepush patch MyApp-iOS -m

# Increase the rollout for v23 to 50%
appsonair-codepush patch MyApp-iOS -l v23 -rollout 50%

Label parameter

Indicates which release (e.g. v23) you want to update within the specified deployment. If omitted, the requested changes will be applied to the latest release in the specified deployment. In order to look up the label for the release you want to update, you can run the appsonair-codepush deployment history command and refer to the Label column.

note

This parameter can be set using either --label or -l

Mandatory parameter

This is the same parameter as the one described in the above section, and simply allows you to update whether the release should be considered mandatory or not. Note that --mandatory and --mandatory true are equivalent, but the absence of this flag is not equivalent to --mandatory false. Therefore, if the parameter is omitted, no change will be made to the value of the target release's mandatory property. You need to set this to --mandatory false to explicitly make a release optional.

Description parameter

This is the same parameter as the one described in the above section, and simply allows you to update the description associated with the release (e.g. you made a typo when releasing, or you forgot to add a description at all). If this parameter is omitted, no change will be made to the value of the target release's description property.

Disabled parameter

This is the same parameter as the one described in the above section, and simply allows you to update whether the release should be disabled or not. Note that --disabled and --disabled true are equivalent, but the absence of this flag is not equivalent to --disabled false. Therefore, if the parameter is omitted, no change will be made to the value of the target release's disabled property. You need to set this to --disabled false to explicitly make a release acquirable if it was previously disabled.

Rollout parameter

This is the same parameter as the one described in the above section, and simply allows you to increase the rollout percentage of the target release. This parameter can only be set to an integer whose value is greater than the current rollout value. Additionally, if you want to "complete" the rollout, and therefore, make the release available to everyone, you can simply set this parameter to --rollout 100. If this parameter is omitted, no change will be made to the value of the target release's rollout parameter.

Additionally, as mentioned above, when you release an update without a rollout value, it is treated equivalently to setting the rollout to 100. Therefore, if you released an update without a rollout, you cannot change the rollout property of it via the patch command since that would be considered lowering the rollout percentage.

Target binary version parameter

This is the same parameter as the one described in the above section, and simply allows you to update the semver range that indicates which binary version(s) a release is compatible with. This can be useful if you made a mistake when originally releasing an update (e.g. you specified 1.0.0 but meant 1.1.0) or you want to increase or decrease the version range that a release supports (e.g. you discovered that a release doesn't work with 1.1.2 after all). If this parameter is omitted, no change will be made to the value of the target release's version property.

Terminal

# Add a "max binary version" to an existing release
# by scoping its eligibility to users running >= 1.0.5
appsonair-codepush patch MyApp-iOS -t "1.0.0 - 1.0.5"

---

Rolling Back Updates

A deployment's release history is immutable, so you cannot delete or remove an update once it has been released. However, if you release an update that is broken or contains unintended features, it is easy to roll it back using the rollback command:

Terminal

appsonair-codepush rollback <appName>
appsonair-codepush rollback MyApp-iOS

This has the effect of creating a new release for the deployment that includes the exact same code and metadata as the version prior to the latest one. For example, imagine that you released the following updates to your app:

Release	Description	Mandatory
v1	Initial release!	Yes
v2	Added new feature	No
v3	Bug fixes	Yes

If you ran the rollback command on that deployment, a new release (v4) would be created that included the contents of the v2 release.

Release	Description	Mandatory
v1	Initial release!	Yes
v2	Added new feature	No
v3	Bug fixes	Yes
v4 (Rollback from v3 to v2)	Added new feature	No

End-users that had already acquired v3 would now be "moved back" to v2 when the app performs an update check. Additionally, any users that were still running v2, and therefore, had never acquired v3, wouldn't receive an update since they are already running the latest release (this is why our update check uses the package hash in addition to the release label).

If you would like to rollback a deployment to a release other than the previous (e.g. v3 -> v2), you can specify the optional --targetRelease parameter:

Terminal

appsonair-codepush rollback MyApp-iOS --targetRelease v34

note

The release produced by a rollback will be annotated in the output of the deployment history command to help identify them more easily.

---

Viewing Release History

You can view a history of the 50 most recent releases for a specific app deployment using the following command:

Terminal

appsonair-codepush deployment history <appName>

The history will display all attributes about each release (e.g. label, mandatory) as well as indicate if any releases were made due to a rollback operation.

Additionally, the history displays the install metrics for each release. You can view the details about how to interpret the metric data in the documentation for the deployment ls command above.

By default, the history doesn't display the author of each release, but if you are collaborating on an app with other developers, and want to view who released each update, you can pass the additional --displayAuthor (or -a) flag to the history command.

note

The history command can also be run using the "h" alias

---

Code Signing for AppsOnAirCodePush

Code Signing ensures that updates deployed via AppsOnAirCodePush are secure and verified. Follow these steps to set up Code Signing:

1. Generate a Signing Key

Create private and public keys using OpenSSL:

Terminal

# generate private RSA key and write it to private.pem file
openssl genrsa -out private.pem

# export public key from private.pem into public.pem
openssl rsa -pubout -in private.pem -out public.pem

2. Configure AppsOnAirCodePush CLI

Specify the path to your private key when releasing updates:

Terminal

appsonair-codepush release-react <appName> <platform> --privateKeyPath private.pem

3. Configure Your App

iOS

Add the public key to your Info.plist:

• Open your Info.plist file.

• Add a new entry:

  Info.plist

  <key>CodePushPublicKey</key>
  <string>-----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
  -----END PUBLIC KEY-----</string>

Replace the placeholder with the actual contents of your public.pem file.

Android

Add the public key to your strings.xml:

• Open res/values/strings.xml.

• Add the following entry:

  strings.xml

  <string name="CodePushPublicKey">-----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
  -----END PUBLIC KEY-----</string>

Replace the placeholder with the actual contents of your public.pem file.