Skip to content
This repository was archived by the owner on Jul 18, 2025. It is now read-only.

Commit b055624

Browse files
chris-cronechris-crone
committed
Rework command help and flags
- Align usage with Docker CLI - Remove short options that are not commonly used - Clarify help and flag messages - Add examples for each command Signed-off-by: Christopher Crone <christopher.crone@docker.com>
1 parent e01fde1 commit b055624

18 files changed

Lines changed: 102 additions & 87 deletions

‎e2e/plugin_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ func TestInvokePluginFromCLI(t *testing.T) {
1515
// docker --help should list app as a top command
1616
cmd.Command = dockerCli.Command("--help")
1717
icmd.RunCmd(cmd).Assert(t, icmd.Expected{
18-
Out: "app* Docker Application Packages (Docker Inc.,",
18+
Out: "app* Docker Application (Docker Inc.,",
1919
})
2020

2121
// docker app --help prints docker-app help
@@ -30,7 +30,7 @@ func TestInvokePluginFromCLI(t *testing.T) {
3030

3131
// docker info should print app version and short description
3232
cmd.Command = dockerCli.Command("info")
33-
re := regexp.MustCompile(`app: Docker Application Packages \(Docker Inc\., .*\)`)
33+
re := regexp.MustCompile(`app: Docker Application \(Docker Inc\., .*\)`)
3434
output := icmd.RunCmd(cmd).Assert(t, icmd.Success).Combined()
3535
assert.Assert(t, re.MatchString(output))
3636
}

‎e2e/testdata/plugin-usage-experimental.golden‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11

22
Usage: docker app COMMAND
33

4-
Build and deploy Docker Application Packages.
4+
A tool to build and manage Docker Applications.
55

66
Commands:
7-
bundle Create a CNAB invocation image and bundle.json for the application
7+
bundle Create a CNAB invocation image and `bundle.json` for the application
88
completion Generates completion scripts for the specified shell (bash or zsh)
9-
init Start building a Docker application
10-
inspect Shows metadata, parameters and a summary of the compose file for a given application
9+
init Initialize Docker Application definition
10+
inspect Shows metadata, parameters and a summary of the Compose file for a given application
1111
install Install an application
12-
merge Merge a multi-file application into a single file
13-
pull Pull an application from a registry
14-
push Push the application to a registry
15-
render Render the Compose file for the application
16-
split Split a single-file application into multiple files
17-
status Get the installation status. If the installation is a docker application, the status shows the stack services.
12+
merge Merge a directory format Docker Application definition into a single file
13+
pull Pull an application package from a registry
14+
push Push an application package to a registry
15+
render Render the Compose file for an Application Package
16+
split Split a single-file Docker Application definition into the directory format
17+
status Get the installation status of an application
1818
uninstall Uninstall an application
1919
upgrade Upgrade an installed application
2020
validate Checks the rendered application is syntactically correct

‎e2e/testdata/plugin-usage.golden‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,20 @@
11

22
Usage: docker app COMMAND
33

4-
Build and deploy Docker Application Packages.
4+
A tool to build and manage Docker Applications.
55

66
Commands:
7-
bundle Create a CNAB invocation image and bundle.json for the application
7+
bundle Create a CNAB invocation image and `bundle.json` for the application
88
completion Generates completion scripts for the specified shell (bash or zsh)
9-
init Start building a Docker application
10-
inspect Shows metadata, parameters and a summary of the compose file for a given application
9+
init Initialize Docker Application definition
10+
inspect Shows metadata, parameters and a summary of the Compose file for a given application
1111
install Install an application
12-
merge Merge a multi-file application into a single file
13-
pull Pull an application from a registry
14-
push Push the application to a registry
15-
render Render the Compose file for the application
16-
split Split a single-file application into multiple files
17-
status Get the installation status. If the installation is a docker application, the status shows the stack services.
12+
merge Merge a directory format Docker Application definition into a single file
13+
pull Pull an application package from a registry
14+
push Push an application package to a registry
15+
render Render the Compose file for an Application Package
16+
split Split a single-file Docker Application definition into the directory format
17+
status Get the installation status of an application
1818
uninstall Uninstall an application
1919
upgrade Upgrade an installed application
2020
validate Checks the rendered application is syntactically correct

‎internal/commands/bundle.go‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,16 @@ type bundleOptions struct {
2828
func bundleCmd(dockerCli command.Cli) *cobra.Command {
2929
var opts bundleOptions
3030
cmd := &cobra.Command{
31-
Use: "bundle [<app-name>]",
32-
Short: "Create a CNAB invocation image and bundle.json for the application",
33-
Args: cli.RequiresMaxArgs(1),
31+
Use: "bundle [APP_NAME] [--output OUTPUT_FILE]",
32+
Short: "Create a CNAB invocation image and `bundle.json` for the application",
33+
Example: `$ docker app bundle myapp.dockerapp`,
34+
Args: cli.RequiresMaxArgs(1),
3435
RunE: func(cmd *cobra.Command, args []string) error {
3536
return runBundle(dockerCli, firstOrEmpty(args), opts)
3637
},
3738
}
3839

39-
cmd.Flags().StringVarP(&opts.out, "output", "o", "bundle.json", "path to the output bundle.json (- for stdout)")
40+
cmd.Flags().StringVarP(&opts.out, "output", "o", "bundle.json", "Output file (- for stdout)")
4041
return cmd
4142
}
4243

‎internal/commands/completion.go‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,20 @@ func completionCmd(dockerCli command.Cli, rootCmd *cobra.Command) *cobra.Command
1414
return &cobra.Command{
1515
Use: "completion SHELL",
1616
Short: "Generates completion scripts for the specified shell (bash or zsh)",
17-
Long: `# Load the docker-app completion code for bash into the current shell
18-
. <(docker-app completion bash)
19-
# Set the docker-app completion code for bash to autoload on startup in your ~/.bashrc,
17+
Long: `# Load the "docker app" completion code for bash into the current shell
18+
. <(docker app completion bash)
19+
# Set the "docker app" completion code for bash to autoload on startup in your ~/.bashrc,
2020
# ~/.profile or ~/.bash_profile
21-
. <(docker-app completion bash)
21+
. <(docker app completion bash)
2222
# Note: bash-completion is needed.
2323
24-
# Load the docker-app completion code for zsh into the current shell
25-
source <(docker-app completion zsh)
26-
# Set the docker-app completion code for zsh to autoload on startup in your ~/.zshrc
27-
source <(docker-app completion zsh)
24+
# Load the "docker app" completion code for zsh into the current shell
25+
source <(docker app completion zsh)
26+
# Set the "docker app" completion code for zsh to autoload on startup in your ~/.zshrc,
27+
source <(docker app completion zsh)
2828
`,
29-
Args: cli.RequiresMaxArgs(1),
29+
Example: `$ . <(docker app completion bash)`,
30+
Args: cli.RequiresMaxArgs(1),
3031
RunE: func(cmd *cobra.Command, args []string) error {
3132
switch {
3233
case len(args) == 0:

‎internal/commands/init.go‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,18 @@ var (
1515

1616
func initCmd() *cobra.Command {
1717
cmd := &cobra.Command{
18-
Use: "init <app-name> [-c <compose-file>] [-d <description>] [-m name:email ...]",
19-
Short: "Start building a Docker application",
20-
Long: `Start building a Docker application. Will automatically detect a docker-compose.yml file in the current directory.`,
21-
Args: cli.ExactArgs(1),
18+
Use: "init APP_NAME [--compose-file COMPOSE_FILE] [--description DESCRIPTION] [--maintainer NAME:EMAIL ...] [OPTIONS]",
19+
Short: "Initialize Docker Application definition",
20+
Long: `Start building a Docker Application package. If there is a docker-compose.yml file in the current directory it will be copied and used.`,
21+
Example: `$ docker app init myapp --description "a useful description"`,
22+
Args: cli.ExactArgs(1),
2223
RunE: func(cmd *cobra.Command, args []string) error {
2324
return packager.Init(args[0], initComposeFile, initDescription, initMaintainers, initSingleFile)
2425
},
2526
}
26-
cmd.Flags().StringVarP(&initComposeFile, "compose-file", "c", "", "Initial Compose file (optional)")
27-
cmd.Flags().StringVarP(&initDescription, "description", "d", "", "Initial description (optional)")
28-
cmd.Flags().StringArrayVarP(&initMaintainers, "maintainer", "m", []string{}, "Maintainer (name:email) (optional)")
29-
cmd.Flags().BoolVarP(&initSingleFile, "single-file", "s", false, "Create a single-file application")
27+
cmd.Flags().StringVar(&initComposeFile, "compose-file", "", "Compose file to use as application base (optional)")
28+
cmd.Flags().StringVar(&initDescription, "description", "", "Human readable description of your application (optional)")
29+
cmd.Flags().StringArrayVar(&initMaintainers, "maintainer", []string{}, "Name and email address of person responsible for the application (name:email) (optional)")
30+
cmd.Flags().BoolVar(&initSingleFile, "single-file", false, "Create a single-file Docker Application definition")
3031
return cmd
3132
}

‎internal/commands/inspect.go‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,10 @@ type inspectOptions struct {
1818
func inspectCmd(dockerCli command.Cli) *cobra.Command {
1919
var opts inspectOptions
2020
cmd := &cobra.Command{
21-
Use: "inspect [<app-name>] [-s key=value...] [-f parameters-file...]",
22-
Short: "Shows metadata, parameters and a summary of the compose file for a given application",
23-
Args: cli.RequiresMaxArgs(1),
21+
Use: "inspect [APP_NAME] [OPTIONS]",
22+
Short: "Shows metadata, parameters and a summary of the Compose file for a given application",
23+
Example: `$ docker app inspect myapp.dockerapp`,
24+
Args: cli.RequiresMaxArgs(1),
2425
RunE: func(cmd *cobra.Command, args []string) error {
2526
return runInspect(dockerCli, firstOrEmpty(args), opts)
2627
},

‎internal/commands/install.go‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,22 +31,25 @@ const (
3131
nameKindReference
3232
)
3333

34-
const longDescription = `Install the application on either Swarm or Kubernetes.
35-
Bundle name is optional, and can:
36-
- be empty and resolve to any *.dockerapp in working directory
37-
- be a BUNDLE file path and resolve to any *.dockerapp file or dir, or any CNAB file (signed or unsigned)
38-
- match a bundle name in the local bundle repository
39-
- refer to a CNAB in a container registry
40-
`
34+
const longDescription = `Install an application.
35+
By default, the application definition in the current directory will be
36+
installed. The APP_NAME can also be:
37+
- a path to a Docker Application definition (.dockerapp) or a CNAB bundle.json
38+
- a registry Application Package reference`
39+
40+
const example = `$ docker app install myapp.dockerapp --name myinstallation --target-context=mycontext
41+
$ docker app install myrepo/myapp:mytag --name myinstallation --target-context=mycontext
42+
$ docker app install bundle.json --name myinstallation --credential-set=mycredentials.yml`
4143

4244
func installCmd(dockerCli command.Cli) *cobra.Command {
4345
var opts installOptions
4446

4547
cmd := &cobra.Command{
46-
Use: "install [<bundle name>] [OPTIONS]",
48+
Use: "install [APP_NAME] [--name INSTALLATION_NAME] [--target-context TARGET_CONTEXT] [OPTIONS]",
4749
Aliases: []string{"deploy"},
4850
Short: "Install an application",
4951
Long: longDescription,
52+
Example: example,
5053
Args: cli.RequiresMaxArgs(1),
5154
RunE: func(cmd *cobra.Command, args []string) error {
5255
return runInstall(dockerCli, firstOrEmpty(args), opts)
@@ -56,7 +59,7 @@ func installCmd(dockerCli command.Cli) *cobra.Command {
5659
opts.credentialOptions.addFlags(cmd.Flags())
5760
opts.registryOptions.addFlags(cmd.Flags())
5861
opts.pullOptions.addFlags(cmd.Flags())
59-
cmd.Flags().StringVarP(&opts.orchestrator, "orchestrator", "o", "", "Orchestrator to install on (swarm, kubernetes)")
62+
cmd.Flags().StringVar(&opts.orchestrator, "orchestrator", "", "Orchestrator to install on (swarm, kubernetes)")
6063
cmd.Flags().StringVar(&opts.kubeNamespace, "kubernetes-namespace", "default", "Kubernetes namespace to install into")
6164
cmd.Flags().StringVar(&opts.stackName, "name", "", "Installation name (defaults to application name)")
6265

‎internal/commands/merge.go‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -61,9 +61,10 @@ func removeAndRename(source, target string) error {
6161

6262
func mergeCmd(dockerCli command.Cli) *cobra.Command {
6363
cmd := &cobra.Command{
64-
Use: "merge [<app-name>] [-o output_file]",
65-
Short: "Merge a multi-file application into a single file",
66-
Args: cli.RequiresMaxArgs(1),
64+
Use: "merge [APP_NAME] [--output OUTPUT_FILE]",
65+
Short: "Merge a directory format Docker Application definition into a single file",
66+
Example: `$ docker app merge myapp.dockerapp --output myapp-single.dockerapp`,
67+
Args: cli.RequiresMaxArgs(1),
6768
RunE: func(cmd *cobra.Command, args []string) error {
6869
extractedApp, err := packager.Extract(firstOrEmpty(args))
6970
if err != nil {

‎internal/commands/pull.go‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,10 @@ import (
1515
func pullCmd(dockerCli command.Cli) *cobra.Command {
1616
var opts registryOptions
1717
cmd := &cobra.Command{
18-
Use: "pull <repotag>",
19-
Short: "Pull an application from a registry",
20-
Args: cli.ExactArgs(1),
18+
Use: "pull NAME:TAG [OPTIONS]",
19+
Short: "Pull an application package from a registry",
20+
Example: `$ docker app pull docker/app-example:0.1.0`,
21+
Args: cli.ExactArgs(1),
2122
RunE: func(cmd *cobra.Command, args []string) error {
2223
return runPull(dockerCli, args[0], opts)
2324
},

0 commit comments

Comments
 (0)