There are 2 main strategies for releasing oclif CLIs: npm and standalone tarballs. You can publish to one or both.
npm publish like any other npm project. This includes a
run.cmd script that will automatically be used for Windows users.
$ npm version (major|minor|patch) # bumps version, updates README, adds git tag
$ npm publish
$ npm install -g mynewcli
$ npx mynewcli
You'll need to register with npm and have verified your email address in order to publish.
This workflow can be improved slightly by running
npm version major|minor|patch before publishing which will create a git tag and bump the version automatically.
Build standalone tarballs with
oclif pack tarballs from the root of your CLI. These include the node binary so the user does not have to already have node installed to use the CLI. It won't put this node binary on the PATH so the binary will not conflict with any node installation on the machine.
To publish, you can copy the files from
./dist or use
oclif upload tarballs to copy the files to S3. You'll need to set
package.json to a valid S3 bucket and have credentials set in
AWS_SECRET_ACCESS_KEY environment vars.
After you've uploaded the tarballs to S3, you can promote the tarballs to a release channel within S3 using
oclif promote. This allows you to quickly promote and demote a specific version between release channels. For example, the Salesforce CLI has separate
stable-rc channels that are updated weekly.
Your formula can be distributed through Brew. The main caveat is you must set the
CLIENT_HOME variable when you ship, otherwise it will break the update cycle. An example of this can be found in the heroku cli formula. By exporting a variable of the form
CLI_NAME is the name of your CLI), you force the update mechanism to look at the brew install location instead of the default (which is
These tarballs as well as the installers below can be made autoupdatable by adding the
@oclif/plugin-update plugin. Just add this plugin and the CLI will autoupdate in the background or when
mycli update is run.
If you don't want to use S3, you can still run
oclif pack and it will build tarballs. To get the updater to work, set
package.json to a host that has the files built in
oclif pack. This host does not need to be an S3 host. To customize the URL paths, see the S3 templates in
You can have separate channels for releases that work like Google Chrome Channels (such as beta, dev, canary). To create a channel, just change the version in
1.0.0-beta (where "beta" is any string you like). Then when you pack with
oclif pack, it will create beta tarballs. The user can change their channel with
mycli update beta and will receive all the future releases on that channel.
In the Heroku CLI, we have it automatically build and release the beta channel on every commit to the master branch. Then we have it build and release stable channel whenever a git tag is created in our CI.
Build a windows installer with
oclif pack win. It will build into
./dist/win. This can be uploaded to S3 with
oclif upload win and promoted within S3 with
oclif promote --win.
The installer uses 7zip and nsis. If you're in a mac or unix environment and don't have them, you can use homebrew to insall them.
brew install nsis
brew install p7zip
Build a macOS .pkg installer with
oclif pack macos. It will build into
./dist/macos. This can be uploaded to S3 with
oclif upload macos and promoted within S3 with
oclif promote --macos. You need to set the macOS identifier at
package.json (we use "com.heroku.cli" and "com.salesforce.cli" as the identifiers for the Heroku CLI and the Salesforce CLI, respectively).
Uploading to S3
The upload command defaults to using the ACL setting
public-read unless another policy is specified under
package.json. However, when creating new S3 buckets, AWS's default recommendation can result in an access error (Code: AccessControlListNotSupported) when trying to upload with the
To address this, consider updating the oclif section of your package.json with the desired ACL setting. The example below demonstrates how to set the acl to bucket-owner-full-control:
Amazon has a userguide here for help how to configure Bucket Policy settings.
Signing the installer
To be able to sign an "installer signing identity" has to be available on the build machine (read more on certificates here).
Make sure such a certificate is created in developer.apple.com and that the certificate is downloaded and installed in the KeyChain of the build machine.
The certificate name has to be specified in the
"sign": "\"3rd Party Mac Developer Installer: myOclifCompany (R2315646)\""
Pay attention to the escaped quotation marks, the certificate name is passed on as an argument to the
pkgbuild command so without quotation marks it might break.
For the Heroku CLI the certificate name is "Developer ID Installer: Heroku INC". And optionally set the keychain with
Installed certificates on the build machine can be viewed in the Keychain Access app.
Build a deb package with
oclif pack deb. Set the
MYCLI_DEB_KEY to a gpg key id to create the gpg files. This will include all the files needed for an apt repository in
./dist/deb. They can be uploaded to S3 with
oclif upload deb and promoted within S3 using
oclif promote --deb.
Once it's published to S3, users can install with the following:
$ wget -qO- https://mys3bucket.s3.amazonaws.com/apt/release.key | apt-key add - # you will need to upload this file manually
$ sudo echo "deb https://mys3bucket.s3.amazonaws.com/apt ./" > /etc/apt/sources.list.d/mycli.list
$ sudo apt update
$ sudo apt install -y mycli
This can be placed in a script for users to install with
curl https://pathto/myscript | sh.
These will not autoupdate as Ubuntu already has a reliable way for users to update their package.
Snap is a great way to distribute Linux CLIs and comes built into Ubuntu 16+. The Heroku CLI's snapcraft.yml file can be easily modified to work with any oclif CLI.