Heroku CLI Autocomplete
Last updated March 13, 2023
Table of Contents
Heroku CLI Autocomplete helps you complete command and flag names when you press the tab key. CLI Autocomplete completes all of the commands in the Heroku CLI and will automatically support new commands as they are added. You can also complete values for some flags and args—including apps, pipelines and config vars.
Installing Autocomplete
To get started, update your CLI and run the setup:
$ heroku update
$ heroku autocomplete
For CLI Autocomplete to work correctly, you must be on the latest version of the Heroku CLI. Updating to the latest version is included in the instructions above.
If you installed the CLI via homebrew and want to use Autocomplete via homebrew’s completions, upgrade the CLI via homebrew for instructions.
The specific instructions you’ll receive depend on whether you are using bash or zsh. After you finish setup, Autocomplete is ready to use with the tab key.
We are not planning to support shells besides bash and zsh at this time.
Command name completion
You can start writing a command and then press tab to see the different possibilities for completing it. You can match against all commands that match a given prefix.
$ heroku <TAB>
addons -- lists your add-ons and attachments
addons:attach -- attach add-on resource to a new app
addons:create -- create an add-on resource
...
For example, pressing tab after typing heroku add
autocompletes to heroku addons
.
In bash shells, autocompletion triggers by pressing tab twice successively.
Flag name completion
Most CLI commands make use of flags to provide additional input. Flags are prefaced with two dashes (--
), such as (--app
). Some commands have many different possible flags. You can view all available flags for each command by typing --
and then the tab key. You can match against all flag names that match a given prefix.
$ heroku apps:info --<TAB>
--app -- (autocomplete) app to run command against
--as -- name for add-on attachment
For example, pressing tab after typing heroku apps:info --a
autocompletes to heroku apps:info --app
.
Flag value completion
Most flags require you to provide a value. For example, --app
requires you to specify the name of an app. With Autocomplete, you can complete values for many popular flags, including --app
,--pipeline
, --space
, and --team
.
$ heroku apps:info --app=<TAB>
staging-app
production-app
For example, if you have the two apps listed in the output above, pressing tab after typing
heroku apps:info --app=p
autocompletes to the following:
heroku apps:info --app=production-app
Not all flags have autocomplete options. Flags that do have these options are tagged with (autocomplete)
during flag name autocompletion. See Completing flag names for an example.
Completion for config vars and add-on names
You can complete config vars and add-on names when the CLI knows the app. The CLI can infer the app via the git remote or you can provide the app name via a flag. We call these kinds of completions “contextual completions”, as the CLI needs context to know how to complete them.
Uninstalling Autocomplete
To uninstall Autocomplete, remove the plugin and delete the autocomplete environment variable from your zsh or bash profile.
$ heroku plugins:uninstall autocomplete