Pruning Pack CLI Commands
Pack CLI v0.16.0 introduces some startling UX changes. Users will see the list of available commands shrink from:
$ pack
Available Commands:
build Generate app image from source code
rebase Rebase app image with latest run image
inspect-image Show information about a built image
inspect-buildpack Show information about a buildpack
set-run-image-mirrors Set mirrors to other repositories ...
set-default-builder Set default builder used by other commands
inspect-builder Show information about a builder
suggest-builders Display list of recommended builders
trust-builder Trust builder
untrust-builder Stop trusting builder
list-trusted-builders List Trusted Builders
create-builder Create builder image
package-buildpack Package buildpack in OCI format.
version Show current 'pack' version
report Display useful information for reporting ...
add-registry (experimental) Add buildpack registry to
list-registries (experimental) List buildpack registries
register-buildpack (experimental) Register the buildpack to ...
set-default-registry (experimental) Set default registry
remove-registry (experimental) Remove registry
yank-buildpack (experimental) Yank the buildpack from ...
completion Outputs completion script location
stack Displays stack information
help Help about any command
to:
$ pack
Available Commands:
build Generate app image from source code
builder Interact with builders
buildpack Interact with buildpacks
config Interact with your local pack config file
stack Interact with stacks
rebase Rebase app image with latest run image
inspect-image Show information about a built image
inspect-buildpack Show information about a buildpack
inspect-builder Show information about a builder
completion Outputs completion script location
report Display useful information for reporting ...
version Show current 'pack' version
help Help about any command
Note: The previous commands were deprecated, but still work as they did. They are just no longer suggested to users, with intention to remove them entirely in one or two releases.
One question remains:
Design
As the number of commands for pack
grew (a whopping 24 in the last release), we realized that it was becoming more and more difficult to identify interworking subcommands with a glance. As such, we wanted to reorganize the commands by resource type, to simplify usage of pack
.
Let’s show this with an example. We had a number of commands focused on manipulating buildpacks:
$ pack
...
package-buildpack Package buildpack in OCI format.
...
register-buildpack (experimental) Register the buildpack to a registry
...
yank-buildpack (experimental) Yank the buildpack from the registry
These commands, while they are linked, weren’t necessarily relevant to users who weren’t buildpack authors, and they could be hard to discover if you were a buildpack author. As such, we have now grouped them as subcommands under a single command, pack buildpack
$ pack buildpack
Interact with buildpacksUsage:
pack buildpack [command]Available Commands:
package Package buildpack in OCI format.
pull (experimental) Pull the buildpack from a registry and store it locally
register (experimental) Register the buildpack to a registry
yank (experimental) Yank the buildpack from the registry
This is a relatively common pattern, as CLIs grow more complex. For example, popular CLIs that have resource based subcommands include docker, gcloud, heroku, and kubectl.
This change also allowed us to make a significant improvement, with the addition of a single command, pack config
. That command now wraps all of functionality for manipulating the configuration file (where we maintain users lists of default-builder
, trusted-builders
, run-image-mirrors
, and more) in a uniform way.
Our Process
This change was a long time coming. The Cloud Native Buildpacks project follows an RFC (Request for Comments) process for substantial changes to the project (described here). As such, platform maintainer Javier Romero created an RFC proposal in July, suggesting that we switch to a resource-based subcommand structure, rather than keeping all commands top-level.
That proposal, after considerable discussion, was merged in September, and issues were created for the various changes required in October. The process was kicked off by a new contributor (thanks anshlykov!) submitting a PR to add a new stack
resource subcommand, and the race was on. Over the past few weeks, we’ve converted most of the previous commands to subcommands of 4 main commands: pack builder
, pack buildpack
, pack config
, and pack stack
.
We think that this should make for a better CLI organization, but ultimately, that depends on you. Try it out, and let us know what you think of the experience by participating in the discussions on slack or Github. In particular, let us know whether you think we should add a new inspect
subcommand to group the three inspect-X
commands we have currently, by participating on Github.
As ever, thanks for contributing to and enjoying the project!