Announcing the New Heroku CLI: Performance and Readability Enhancements

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.

Tuned for Performance

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.

Performance_windows

Installing the New CLI

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/heroku directory 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!

Improved Readability for Humans and Machines

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.

grep-parseable Output

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 grep.

For example, let’s look at heroku regions. heroku regions at one point showed output like the following:

heroku_regions_old

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:

heroku_regions_new

Now you can use grep to filter just common runtime spaces:

heroku_regions_grep

Power Up with the jq Tool

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.

heroku_regions_jq

$ heroku

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.

heroku_dashboard

Colors

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 COLOR=false.

Input Commands: Flags and Args

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.

An old 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.

The new heroku fork has required flags:

$ heroku fork --from sourceapp --to destapp

The input flags specify the source and destination with --from and --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.

Learn More

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.

As always, we love getting feedback from you so try out the new CLI and let us know your thoughts.

Video Transcript