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 $ mynewcli # OR $ 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.
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).
To sign the installer, set
package.json to a certificate (For the Heroku CLI this is "Developer ID Installer: Heroku INC"). And optionally set the keychain with
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.