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. We like to use np which is like
npm version, but will also run the tests and other health checks before publishing.
Build standalone tarballs with
oclif-dev pack 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-dev publish 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.
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-dev pack and it will build tarballs. To get the updater to work, set
oclif.update.s3.host to a host that has the files built in
oclif-dev 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-dev 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-dev pack:win. It will build into
./dist/win. This can be published to S3 with
Build a MacOS .pkg installer with
oclif-dev pack:macos. It will build into
./dist/macos. This can be published to S3 with
oclif-dev publish:macos. You need to set the MacOS identifier at
package.json. (For the Heroku CLI we use "com.heroku.cli" as the identifier)
To sign the installer, set
oclif.macos.sign 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-dev 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 published to S3 with
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.