Today we are announcing the newest version of the Heroku CLI. We know how much time you spend in the CLI as developers and how much pride you take in being able to get things done quickly. Our new CLI has big improvements in performance as well as enhanced readability for humans and machines.
CLI response time is made up of two parts: the API response time and the performance of the CLI itself, and the latter is where we’ve made big improvements. While a typical Unix user should experience responses that are around half a second faster, the biggest gains are for Windows users, as the new CLI no longer has a Ruby wrapper.
When we measured the time it takes for the info command in the old vs. new CLI, it decreases from 1690 to 1210 milliseconds in Unix, and 3409 to 944 milliseconds in Windows! Though individual results will vary, you should experience faster response times on average across all commands.
You might have noticed some improvements over the last few months, but to get the fastest version you’ll need to uninstall and reinstall the CLI, because we’ve rewritten it in Node.js with new installers. The good news is that this should be the last manual update you’ll ever do for the Heroku CLI: the new CLI will auto-update in the future.
The instructions to uninstall for Mac OS X users are to type the following:
$ rm -rf /usr/local/heroku $ rm -rf ~/.heroku ~/.local/share/heroku ~/.config/heroku ~/.cache/heroku
Then download and run the OS X installer.
On Windows, to uninstall the Heroku CLI:
- Click Start > Control Panel > Programs > Programs and Features.
- Select Heroku CLI, and then click Uninstall.
- Delete the
.config/herokudirectory inside your home directory.
Then download and run the Windows installer.
For the last few of you who are still using our very old Ruby gem - now is a great time to upgrade to the full Heroku CLI experience. Please let us know if you run into any issues with installation as we’re here to help!
The new CLI includes a number of user experience improvements that we’ve been rolling out over the past few months. Here are some of our favorites.
We’ve learned that while you value human-readable output, you want
grep-parseable output too. We’ve standardized the output format to make it possible to use
For example, let’s look at
heroku regions at one point showed output like the following:
While this shows all the information about the available regions, and is arguably more readable for humans as it groups the two regions underneath their respective headers, you lose the ability to use
grep to filter the data. Here is a better way to display this information:
Now you can use
grep to filter just common runtime spaces:
If you want even better tools to work with a richer CLI output, many commands support a
--json flag. Use the powerful
jq tool to query the results.
We noticed that
heroku was one of the top commands users run. We learned that many users were running it to get a holistic overview of their account. We re-ordered the output so it would be in an order that would make sense to you - and showing your starred apps first. We also added context that would give you a Dashboard-style view of the current state of those apps and how they fit into the bigger picture, including pipeline info, last release info, metrics, and errors. At the end of the output, we give guidance on where you might want to go next - such as viewing add-ons or perhaps apps in a particular org.
We’ve used color to help you quickly read command output. We’ve given some nouns in the CLI standard colors, so that you’ll easily spot them. In the example above you’ll notice that apps are purple, example commands are in blue, and the number of unread notifications is green. We typically specify errors and warning messages in yellow and red.
We’ve tried to be mindful with color. Too many contrasting colors in the same place can quickly begin to compete for attention and reduce readability. We also make sure color is never the only way we communicate information.
You can always disable color as a user, by adding
--no-color or setting
Our new CLI makes greater use of flags over args. Flags provide greater clarity and readability, and give you confidence that you are running the command correctly.
heroku fork command would look like this:
$ heroku fork destapp -a sourceapp
Which app is being forked and which app is the destination app? It’s not clear.
heroku fork has required flags:
$ heroku fork --from sourceapp --to destapp
The input flags specify the source and destination with
--to so that it’s very clear. You can specify these flags in any order, and still be sure that you will get the correct result.
Looking to the future, flags will allow us to provide autocomplete in a much better fashion than args. This is because when the user types:
$ heroku info --app <tab><tab>
...we know without question that the next thing to complete is an app name and not another flag or other type of argument.
These are just some examples of the work we’ve been doing to standardize and improve the Heroku CLI user experience. You can read more in the Heroku Dev Center CLI article. We’ve also published a CLI style guide that documents our point of view on CLI design and provides a clear direction for designing delightful CLI plugins.