Docker CLI

Docker CLI is the docker command itself — the client binary that talks to the Docker Engine (and to Swarm and BuildKit) over its API to manage containers, images, networks, volumes, contexts, and secrets. It ships as a single static Go binary built around spf13/cobra, with every subcommand (docker run, docker build, docker compose, docker context, etc.) wired up in cli/command/commands and dispatched through a shared command.Cli interface that carries the API client, output streams, and configuration.

Beyond the built-in command tree, the CLI implements Docker’s plugin protocol in cli-plugins/manager: any executable named docker-<name> on the user’s PATH (or in a well-known plugin directory) is discovered, version-checked, and invoked as if it were a native subcommand. This is how docker compose, docker buildx, and docker scan are distributed as separate binaries while still feeling like first-class docker commands — including shared flag parsing, telemetry, and shell completion.

The project also owns Docker’s client-side context system (cli/context), which lets a single CLI installation switch between local, remote SSH, and cloud endpoints, and the credential-helper integration that keeps registry logins out of plaintext config files. It’s maintained directly by Docker, Inc. and Moby maintainers and is the reference implementation other Docker-compatible CLIs (Podman’s docker-compatible mode, various CI tooling) measure themselves against.

What You Get

• The full docker command tree — run, build, ps, exec, logs, network, volume, swarm, stack, secret, config, and dozens more, all defined in cli/command
• A documented plugin protocol (cli-plugins/manager) so a standalone binary named docker-<name> is discovered and invoked as docker <name>, complete with version negotiation and shell completion
• The client-side context system (cli/context) for switching between local, SSH-remote, and cloud Docker endpoints without re-authenticating each time
• Built-in registry credential-helper integration so login tokens can live in the OS keychain instead of config.json
• Formatter and template infrastructure (cli/command/formatter) so every list/inspect command supports --format with Go templates and JSON output
• OpenTelemetry-instrumented command execution for usage and error telemetry, controllable per the Docker CLI’s opt-out settings

Common Use Cases

• Local container development - engineers run docker build/docker run/docker exec day-to-day to build and iterate on containerized services
• CI pipelines - build agents shell out to the same docker binary to build, tag, and push images as part of automated pipelines
• Docker Compose and Buildx workflows - docker compose up and docker buildx bake are plugin binaries invoked transparently through this CLI’s plugin manager
• Multi-context operations - teams managing several Docker hosts (local, staging VM over SSH, cloud) use docker context to switch targets without re-typing -H flags
• Swarm and stack management - docker service, docker stack deploy, and docker node commands drive Docker Swarm orchestration directly from this CLI
• Building Docker-compatible tooling - other projects vendor packages from cli/command and cli/config to reuse Docker’s flag parsing and config-file handling

Under The Hood

Architecture Execution starts in cmd/docker/docker.go, which builds a root cobra.Command, wires in cli/command.NewDockerCli() for the shared client/streams/config state, and registers the full command tree from cli/command/commands. Every subcommand implements a common pattern — a NewXCmd(dockerCli command.Cli) *cobra.Command constructor that closures over the shared command.Cli interface, so run, build, network, service, and the rest all share one API client, one config store, and one output stream set rather than each wiring their own. Unrecognized top-level commands fall through to cli-plugins/manager, which resolves them against docker-<name> binaries on PATH and re-execs with the parent’s flags and a socket-based handshake (cli-plugins/socket) for passing file descriptors like stdin/stdout to the plugin process. Client-side multi-host support lives in cli/context, a separate store of named endpoint configs (TLS material, SSH targets) that command.Cli resolves against at startup. This layered design — cobra tree, shared Cli interface, plugin fallback, context store — means changing the command.Cli interface has the widest blast radius in the codebase, since virtually every command file depends on it directly.

Tech Stack The module is pure Go (1.26) built on spf13/cobra v1.10 and spf13/pflag for command/flag parsing, with moby/moby/client and moby/moby/api as the generated Docker Engine API client and types. Distinctively, the repo has no go.mod — it uses a vendor.mod instead, explicitly because Docker’s CalVer release scheme (e.g. v29.7.2+incompatible) doesn’t fit Go modules’ SemVer compatibility rules, so consumers pull it as a pseudo-version. Swarm-mode support pulls in moby/swarmkit/v2; observability runs through the full go.opentelemetry.io/otel stack (traces, metrics, OTLP gRPC exporters) wired into command execution; registry auth integrates via docker/docker-credential-helpers; and output formatting/manifest handling leans on opencontainers/image-spec and docker/distribution. The build system itself is Docker-based — docker buildx bake builds cross-platform release binaries, reinforcing the project’s own tooling as its own build dependency.

Code Quality Testing is extensive and conventional Go: 300+ _test.go files sit alongside their implementation files throughout cli/command, cli-plugins, and cmd/docker, using the standard library testing package plus gotest.tools assertions (visible in vendor.mod) rather than a heavier framework. Error handling favors explicit returns and Go 1.20+ error wrapping (errors.As/errdefs.IsCanceled checks in cmd/docker/docker.go) over panics. .golangci.yml configures an extensive linter set enforced in CI (.github/workflows), and docker buildx bake lint shellcheck runs both Go and shell linting as part of the standard build target — shell scripts get the same rigor as Go code, notable given the repo also ships install/completion shell scripts. Naming is consistent with idiomatic Go and Cobra conventions (NewXCmd, runX) throughout the command packages.

API Design The CLI’s real “API” is twofold — the command-line surface itself, and the plugin protocol that lets third parties extend it. The command surface is highly consistent: every subcommand follows the same --format/--filter/--quiet flag vocabulary via the shared formatter package, so learning docker ps --format transfers directly to docker images --format. The plugin protocol is the more interesting developer-facing surface — it’s a documented, versioned handshake (metadata query, API version negotiation, socket-based fd passing) that lets an entirely separate binary like docker-compose or docker-buildx behave indistinguishably from a built-in command, including shared shell completion. That’s a genuinely uncommon amount of ceremony for a CLI plugin system, and it’s what lets Docker’s ecosystem (Compose, Buildx, Scout, and third-party plugins) stay decoupled release-wise while presenting as one unified docker command.