API Endpoints for docker/cli

Routes Defined in the Docker CLI Codebase

In the Docker CLI codebase, the routes are primarily defined and managed through Go code, particularly in the context of command functionalities. The routes correspond to the commands and their subcommands that the Docker CLI supports. Below is a detailed exploration of how these routes are defined, including code examples to illustrate their implementations.

Command Definition in Go

The core of the Docker CLI’s routing logic can be found in the command definition files, typically located within the cli folder. Each command is defined as a struct that embeds the command.Command type. Here is an example of how a command is structured:

package mycommands

import (
"github.com/docker/cli/cli/command"
"github.com/docker/cli/cli/flags"
)
func NewMyCommand(dockerCli command.Cli) command.Command {
return command.Command{
Use:   "mycommand",
Short: "Description of my command",
RunE: func(cmd *command.Command, args []string) error {
// Implement command functionality here
return nil
},
}
}

In this example, mycommand is a new command added to the Docker CLI. The RunE function defines the execution logic for the command.

Command Registration

Commands are registered in the command registry typically found in cli/command. For example:

package root

import (
"github.com/docker/cli/cli/commands/mycommands"
)
func init() {
// Register subcommands
rootCmd.AddCommand(mycommands.NewMyCommand())
}

The rootCmd is the main command under which all other commands are nested. This hierarchical structure allows for complex routing based on command depth.

Subcommands

Subcommands are an important aspect of routing in Docker CLI. For instance, consider the definition of a ps command with subcommands:

func NewPsCommand(dockerCli command.Cli) command.Command {
cmd := &command.Command{
Use:   "ps",
Short: "List containers",
}

cmd.AddCommand(NewPsFilterCommand(dockerCli))
return cmd
}

Here, the NewPsCommand function creates a command for listing containers and nests another command, NewPsFilterCommand, under it. This allows users to utilize commands like docker ps --filter.

Command Flags

Flags provide additional routing details for commands, allowing users to modify the command behavior with options. A command may define flags as follows:

flags := command.FlagSet{}
flags.String("filter", "", "Filter output based on conditions provided")
cmd.Flags().AddFlagSet(flags)

The above snippet associates a filter flag with the ps command, enhancing its routing capabilities by allowing the CLI to handle varying input conditions.

Configuration with HCL

While most routes are defined in Go, there might be configurations set in HCL files that dictate how commands interact with external systems or orchestrators.

command {
name = "ps"
description = "List running containers"

flags {
filter = "String"
}
}

In this HCL snippet, the ps command is configured with a filter flag, specifying its type and its intended usage.

Building the CLI

To build the Docker CLI, use the following command within your project structure:

go build -o docker ./cmd/docker

Ensure that you are not using -mod=vendor as per the project’s guidelines.

Conclusion

Understanding the routing defined in the Docker CLI codebase involves examining how commands and subcommands are structured in Go, their registration, and the manipulation of flags. By looking at these details, developers can gain insights into how each command is handled within the application.

References:

• Code snippets and patterns are derived from the relevant sections of the Docker CLI source code.