You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on May 20, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: cli/README.md
+88-33Lines changed: 88 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,19 +2,21 @@
2
2
3
3
CodePush is a cloud service that enables Cordova and React Native developers to deploy mobile app updates directly to their users' devices. It works by acting as a central repository that developers can publish updates to (JS, HTML, CSS and images), and that apps can query for updates from (using the provided client SDKs for [Cordova](http://github.com/Microsoft/cordova-plugin-code-push) and [React Native](http://github.com/Microsoft/react-native-code-push)). This allows you to have a more deterministic and direct engagement model with your user base, when addressing bugs and/or adding small features that don't require you to re-build a binary and re-distribute it through the respective app stores.
@@ -34,9 +36,10 @@ CodePush is a cloud service that enables Cordova and React Native developers to
34
36
2. Register your [app](#app-management) with CodePush, and optionally [share it](#app-collaboration) with other developers on your team
35
37
3. CodePush-ify your app and point it at the deployment you wish to use ([Cordova](http://github.com/Microsoft/cordova-plugin-code-push) and [React Native](http://github.com/Microsoft/react-native-code-push))
36
38
4.[Release](#releasing-updates) an update for your app
37
-
5. Live long and prosper! ([details](https://en.wikipedia.org/wiki/Vulcan_salute))
39
+
5. Check out the [debug logs](#debugging-codepush-integration) to ensure everything is working as expected
40
+
6. Live long and prosper! ([details](https://en.wikipedia.org/wiki/Vulcan_salute))
38
41
39
-
## Account creation
42
+
## Account Management
40
43
41
44
Before you can begin releasing app updates, you need to create a CodePush account. You can do this by simply running the following command once you've installed the CLI:
42
45
@@ -48,19 +51,19 @@ This will launch a browser, asking you to authenticate with either your GitHub o
48
51
49
52
*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.*
50
53
51
-
If you have an existing account, you may also link your account to another identity provider by running:
54
+
If you have an existing account, you may also link your account to another identity provider (e.g. Microsoft, GitHub) by running:
52
55
53
56
```
54
57
code-push link
55
58
```
56
59
57
-
Note that in order to do this, the email address used on the provider must match the one on your existing account.
60
+
*Note: In order to link multiple accounts, the email address associated with each provider must match.*
58
61
59
-
## Authentication
62
+
###Authentication
60
63
61
64
Most commands within the CodePush CLI require authentication, and therefore, before you can begin managing your account, you need to login using the GitHub or Microsoft account you used when registering. You can do this by running the following command:
62
65
63
-
```
66
+
```shell
64
67
code-push login
65
68
```
66
69
@@ -70,14 +73,13 @@ By default, the login command supports proxies and will look for system environm
70
73
71
74
CodePush specific proxy settings are also supported and can be set using the `--proxy` flag:
72
75
73
-
```
74
-
code-push login --proxy proxyUrl
76
+
```shell
77
+
code-push login --proxy <proxyURL>
75
78
```
76
79
77
-
78
80
Alternatively, proxy functionality can be disabled (system environment variables are suppressed and CodePush ignores proxy settings) by passing the `--noproxy` flag:
79
81
80
-
```
82
+
```shell
81
83
code-push login --noproxy
82
84
```
83
85
@@ -89,40 +91,43 @@ code-push whoami
89
91
90
92
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:
91
93
92
-
```
94
+
```shell
93
95
code-push logout
94
96
```
95
97
96
-
If you forget to logout from a machine you'd prefer not to leave a running session on (e.g. your friend's laptop), you can use the following commands to list and remove any "live" access keys.
97
-
The list of access keys will display the name of the machine the key was created on, the time the login occurred, and the time it expires. This should make it easy to spot keys you don't want to keep around.
98
+
If you forget to logout from a machine you'd prefer not to leave a running session on (e.g. your friend's laptop), you can use the following commands to list and remove any current login sessions.
98
99
99
-
```
100
-
code-push access-key ls
101
-
code-push access-key rm <accessKeyName>
100
+
```shell
101
+
code-push session ls
102
+
code-push session rm <machineName>
102
103
```
103
104
104
-
If you need additional keys that can be used to authenticate against the CodePush service without needing to give access to your GitHub and/or Microsoft credentials, you can run the following command to create a persistent one (along with a name describing what it is for):
105
+
### Access Keys
105
106
106
-
```
107
+
If you need to be able to authenticate against the CodePush service without launching a browser and/or without needing to use your GitHub and/or Microsoft credentials (e.g. in a CI environment), you can run the following command to create an "access key" (along with a name describing what it is for):
108
+
109
+
```shell
107
110
code-push access-key add "VSTS Integration"
108
111
```
109
112
110
113
By default, access keys expire in 60 days. You can specify a different expiry duration by using the `--ttl` option and passing in a [human readable duration string](https://github.com/jkroso/parse-duration#parsestr) (e.g. "2d" => 2 days, "1h 15 min" => 1 hour and 15 minutes). For security, the key will only be shown once on creation, so remember to save it somewhere if needed!
111
114
112
115
After creating the new key, you can specify its value using the `--accessKey` flag of the `login` command, which allows you to perform "headless" authentication, as opposed to launching a browser.
113
116
114
-
```
117
+
```shell
115
118
code-push login --accessKey <accessKey>
116
119
```
117
120
118
-
When logging in via this method, the access key will not be automatically invalidated on logout, and can be used in future sessions until it is explicitly removed from the CodePush server. However, it is still recommended to log out once your session is complete, in order to remove your credentials from disk.
121
+
When logging in via this method, the access key will not be automatically invalidated on logout, and can be used in future sessions until it is explicitly removed from the CodePush server or expires. However, it is still recommended that you log out once your session is complete, in order to remove your credentials from disk.
119
122
120
-
Finally, if you need to change a key's name or expiry date, you can use the following command:
123
+
Finally, if at any point you need to change a key's name and/or expiration date, you can use the following command:
121
124
122
-
```
125
+
```shell
123
126
code-push access-key patch <accessKeyName> --name "new name" --ttl 10d
124
127
```
125
128
129
+
*NOTE: When patching the TTL of an existing access key, its expiration date will be set relative to the current time, with no regard for its previous value.*
130
+
126
131
## App Management
127
132
128
133
Before you can deploy any updates, you need to register an app with the CodePush service using the following command:
@@ -436,15 +443,15 @@ Achieving the equivalent behavior with the `release-react` command would simply
436
443
code-push release-react MyApp ios
437
444
```
438
445
439
-
*NOTE: We believe that the `release-react` command should be valuable for most React Native developers, so if you're finding that it isn't flexible enough or missing a key feature, please don't hesistate to [let us know](mailto:codepushfeed@microsoft.com), so that we can improve it.*
446
+
*NOTE: We believe that the `release-react` command should be valuable for most React Native developers, so if you're finding that it isn't flexible enough or missing a key feature, please don't hesistate to [let us know](mailto:codepushfeed@microsoft.com), so that we can improve it!*
440
447
441
448
#### App name parameter
442
449
443
450
This is the same parameter as the one described in the [above section](#app-name-parameter).
444
451
445
452
#### Platform parameter
446
453
447
-
This specifies which platform the current update is targeting, and can be either `android`, `ios` or `windows` (case-insensitive).
454
+
This specifies which platform the current update is targeting, and can be either `android`, `ios` or `windows` (case-insensitive). This value is only used to determine how to properly bundle your update contents and isn't actually sent to the server.
448
455
449
456
#### Deployment name parameter
450
457
@@ -466,27 +473,53 @@ This is the same parameter as the one described in the [above section](#rollout-
466
473
467
474
This is the same parameter as the one described in the [above section](#target-binary-version-parameter). 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.
468
475
469
-
#### Disabled parameter
476
+
#### Bundle name parameter
470
477
471
-
This is the same parameter as the one described in the [above section](#disabled-parameter).
478
+
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), `index.android.bundle` (Android) and `index.windows.bundle` (Windows).
479
+
480
+
*NOTE: This parameter can be set using either --bundleName or -b*
472
481
473
482
#### Development parameter
474
483
475
484
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.
476
485
477
486
*NOTE: This parameter can be set using either --development or --dev*
478
487
488
+
#### Disabled parameter
489
+
490
+
This is the same parameter as the one described in the [above section](#disabled-parameter).
491
+
479
492
#### Entry file parameter
480
493
481
494
This specifies the relative path to the app's root/entry JavaScript file. If left unspecified, this defaults to `index.ios.js` (for iOS), `index.android.js` (for Android) or `index.windows.bundle` (for Windows) if that file exists, or `index.js` otherwise.
482
495
483
496
*NOTE: This parameter can be set using either --entryFile or -e*
484
497
485
-
#### Bundle name parameter
498
+
#### Plist file parameter
486
499
487
-
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), `index.android.bundle` (Android) and `index.windows.bundle` (Windows).
500
+
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 (e.g. `STAGING-Info.plist`). 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 CodePush updates, without needing to explicitly set the `--targetBinaryVersion` parameter.
488
501
489
-
*NOTE: This parameter can be set using either --bundleName or -b*
*NOTE: This parameter can be set using either --plistFile or -p*
507
+
508
+
#### Plist file prefix parameter
509
+
510
+
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've created per-environment plist files (e.g. `DEV-Info.plist`, `STAGING-Info.plist`), and you want to be able to release CodePush updates without needing to explicity 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.
511
+
512
+
```shell
513
+
# Auto-detect the target binary version of this release by looking up the
514
+
# app version within the STAGING-Info.plist file in either the ./ios or ./ios/<APP> directories.
515
+
code-push release-react foo ios --pre "STAGING"
516
+
517
+
# Tell the CLI to use your dev plist (`DEV-Info.plist`).
518
+
# Note that the hyphen separator can be explicitly stated.
519
+
code-push release-react foo ios --pre "DEV-"
520
+
```
521
+
522
+
*NOTE: This parameter can be set using either --plistFilePrefix or --pre*
490
523
491
524
#### Sourcemap output parameter
492
525
@@ -565,6 +598,28 @@ Specifies whether you want to run `cordova build` instead of `cordova prepare` (
565
598
566
599
*NOTE: This parameter can be set using either --build or -b*
567
600
601
+
## Debugging CodePush Integration
602
+
603
+
Once you've released an update, and the Cordova or 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 CodePush update discovery experience, you can run the following command in order to easily view the diagnostic logs produced by the CodePush plugin wihtin your app:
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 CodePush plugin, for both Cordova or React Native. This, you don't need to learn and/or use another tool simply to be able to answer basic questions about how CodePush is behaving.
620
+
621
+
*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.*
622
+
568
623
## Patching Update Metadata
569
624
570
625
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:
@@ -734,4 +789,4 @@ You can clear the release history associated with a deployment using the followi
After running this command, client devices configured to receive updates using its associated deployment key will no longer receive the updates that have been cleared. This command is irreversible, and therefore should not be used in a production deployment.
792
+
After running this command, client devices configured to receive updates using its associated deployment key will no longer receive the updates that have been cleared. This command is irreversible, and therefore should not be used in a production deployment.
0 commit comments