fix(loader): Allows multiple protocols on one port

[27.x] update to go1.22.12

.github/workflows/build.yml

@@ -1,5 +1,14 @@
 name: build
 
+# Default to 'contents: read', which grants actions to read commits.
+#
+# If any permission is set, any permission not included in the list is
+# implicitly set to "none".
+#
+# see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -13,6 +22,7 @@ on:
     branches:
       - 'master'
       - '[0-9]+.[0-9]+'
+      - '[0-9]+.x'
     tags:
       - 'v*'
   pull_request:

.github/workflows/codeql.yml

@@ -1,10 +1,20 @@
 name: codeql
 
+# Default to 'contents: read', which grants actions to read commits.
+#
+# If any permission is set, any permission not included in the list is
+# implicitly set to "none".
+#
+# see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions
+permissions:
+  contents: read
+
 on:
   push:
     branches: 
       - 'master' 
       - '[0-9]+.[0-9]+' 
+      - '[0-9]+.x'
     tags: 
       - 'v*' 
   pull_request:
@@ -58,7 +68,7 @@ jobs:
         name: Update Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.21'
+          go-version: "1.22.12"
       -
         name: Initialize CodeQL
         uses: github/codeql-action/init@v3

.github/workflows/e2e.yml

@@ -1,5 +1,14 @@
 name: e2e
 
+# Default to 'contents: read', which grants actions to read commits.
+#
+# If any permission is set, any permission not included in the list is
+# implicitly set to "none".
+#
+# see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -10,6 +19,7 @@ on:
     branches:
       - 'master'
       - '[0-9]+.[0-9]+'
+      - '[0-9]+.x'
     tags:
       - 'v*'
   pull_request:
@@ -28,9 +38,8 @@ jobs:
           - alpine
           - debian
         engine-version:
-          - 27-rc # testing
-          - 26.1  # latest
-          - 25.0  # latest - 1
+          - 27.0  # latest
+          - 26.1  # latest - 1
           - 23.0  # mirantis lts
           # TODO(krissetto) 19.03 needs a look, doesn't work ubuntu 22.04 (cgroup errors). 
           # we could have a separate job that tests it against ubuntu 20.04

.github/workflows/test.yml

@@ -1,5 +1,14 @@
 name: test
 
+# Default to 'contents: read', which grants actions to read commits.
+#
+# If any permission is set, any permission not included in the list is
+# implicitly set to "none".
+#
+# see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -10,6 +19,7 @@ on:
     branches:
       - 'master'
       - '[0-9]+.[0-9]+'
+      - '[0-9]+.x'
     tags:
       - 'v*'
   pull_request:
@@ -46,7 +56,8 @@ jobs:
       fail-fast: false
       matrix:
         os:
-          - macos-12
+          - macos-13  # macOS 13 on Intel
+          - macos-14  # macOS 14 on arm64 (Apple Silicon M1)
 #          - windows-2022 # FIXME: some tests are failing on the Windows runner, as well as on Appveyor since June 24, 2018: https://ci.appveyor.com/project/docker/cli/history
     steps:
       -
@@ -64,7 +75,7 @@ jobs:
         name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: 1.21.11
+          go-version: "1.22.12"
       -
         name: Test
         run: |

.github/workflows/validate-pr.yml

@@ -1,5 +1,14 @@
 name: validate-pr
 
+# Default to 'contents: read', which grants actions to read commits.
+#
+# If any permission is set, any permission not included in the list is
+# implicitly set to "none".
+#
+# see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions
+permissions:
+  contents: read
+
 on:
   pull_request:
     types: [opened, edited, labeled, unlabeled]
@@ -53,10 +62,16 @@ jobs:
       # Backports or PR that target a release branch directly should mention the target branch in the title, for example:
       # [X.Y backport] Some change that needs backporting to X.Y
       # [X.Y] Change directly targeting the X.Y branch
-      - name: Get branch from PR title
-        id: title_branch
-        run: echo "$PR_TITLE" | sed -n 's/^\[\([0-9]*\.[0-9]*\)[^]]*\].*/branch=\1/p' >> $GITHUB_OUTPUT
-
       - name: Check release branch
-        if: github.event.pull_request.base.ref != steps.title_branch.outputs.branch && !(github.event.pull_request.base.ref == 'master' && steps.title_branch.outputs.branch == '')
-        run: echo "::error::PR title suggests targetting the ${{ steps.title_branch.outputs.branch }} branch, but is opened against ${{ github.event.pull_request.base.ref }}" && exit 1
+        id: title_branch
+        run: |
+          # get the intended major version prefix ("[27.1 backport]" -> "27.") from the PR title.
+          [[ "$PR_TITLE" =~ ^\[([0-9]*\.)[^]]*\] ]] && branch="${BASH_REMATCH[1]}"
+
+          # get major version prefix from the release branch ("27.x -> "27.")
+          [[ "$GITHUB_BASE_REF" =~ ^([0-9]*\.) ]] && target_branch="${BASH_REMATCH[1]}" || target_branch="$GITHUB_BASE_REF"
+
+          if [[ "$target_branch" != "$branch" ]] && ! [[ "$GITHUB_BASE_REF" == "master" && "$branch" == "" ]]; then
+              echo "::error::PR is opened against the $GITHUB_BASE_REF branch, but its title suggests otherwise."
+              exit 1
+          fi

.github/workflows/validate.yml

@@ -1,5 +1,14 @@
 name: validate
 
+# Default to 'contents: read', which grants actions to read commits.
+#
+# If any permission is set, any permission not included in the list is
+# implicitly set to "none".
+#
+# see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -10,6 +19,7 @@ on:
     branches:
       - 'master'
       - '[0-9]+.[0-9]+'
+      - '[0-9]+.x'
     tags:
       - 'v*'
   pull_request:

.golangci.yml

@@ -1,12 +1,12 @@
 linters:
   enable:
     - bodyclose
+    - copyloopvar   # Detects places where loop variables are copied.
     - depguard
     - dogsled
     - dupword       # Detects duplicate words.
     - durationcheck
     - errchkjson
-    - exportloopref # Detects pointers to enclosing loop variables.
     - gocritic      # Metalinter; detects bugs, performance, and styling issues.
     - gocyclo
     - gofumpt       # Detects whether code was gofumpt-ed.
@@ -54,6 +54,13 @@ linters-settings:
             desc: The io/ioutil package has been deprecated, see https://go.dev/doc/go1.16#ioutil
   gocyclo:
     min-complexity: 16
+  gosec:
+    excludes:
+      - G104 # G104: Errors unhandled; (TODO: reduce unhandled errors, or explicitly ignore)
+      - G113 # G113: Potential uncontrolled memory consumption in Rat.SetString (CVE-2022-23772); (only affects go < 1.16.14. and go < 1.17.7)
+      - G115 # G115: integer overflow conversion; (TODO: verify these: https://github.com/docker/cli/issues/5584)
+      - G306 # G306: Expect WriteFile permissions to be 0600 or less (too restrictive; also flags "0o644" permissions)
+      - G307 # G307: Deferring unsafe method "*os.File" on type "Close" (also EXC0008); (TODO: evaluate these and fix where needed: G307: Deferring unsafe method "*os.File" on type "Close")
   govet:
     enable:
       - shadow
@@ -89,6 +96,10 @@ issues:
   # The default exclusion rules are a bit too permissive, so copying the relevant ones below
   exclude-use-default: false
 
+  # This option has been defined when Go modules was not existed and when the
+  # golangci-lint core was different, this is not something we still recommend.
+  exclude-dirs-use-default: false
+
   exclude:
     - parameter .* always receives
 
@@ -106,6 +117,9 @@ issues:
     #
     # These exclusion patterns are copied from the default excluses at:
     # https://github.com/golangci/golangci-lint/blob/v1.44.0/pkg/config/issues.go#L10-L104
+    #
+    # The default list of exclusions can be found at:
+    # https://golangci-lint.run/usage/false-positives/#default-exclusions
 
     # EXC0001
     - text: "Error return value of .((os\\.)?std(out|err)\\..*|.*Close|.*Flush|os\\.Remove(All)?|.*print(f|ln)?|os\\.(Un)?Setenv). is not checked"
@@ -123,11 +137,6 @@ issues:
     - text: "Subprocess launch(ed with variable|ing should be audited)"
       linters:
         - gosec
-    # EXC0008
-    # TODO: evaluate these and fix where needed: G307: Deferring unsafe method "*os.File" on type "Close" (gosec)
-    - text: "G307"
-      linters:
-        - gosec
     # EXC0009
     - text: "(Expect directory permissions to be 0750 or less|Expect file permissions to be 0600 or less)"
       linters:
@@ -137,26 +146,6 @@ issues:
       linters:
         - gosec
 
-    # G113 Potential uncontrolled memory consumption in Rat.SetString (CVE-2022-23772)
-    # only affects gp < 1.16.14. and go < 1.17.7
-    - text: "G113"
-      linters:
-        - gosec
-    # TODO: G104: Errors unhandled. (gosec)
-    - text: "G104"
-      linters:
-        - gosec
-    # Looks like the match in "EXC0007" above doesn't catch this one
-    # TODO: consider upstreaming this to golangci-lint's default exclusion rules
-    - text: "G204: Subprocess launched with a potential tainted input or cmd arguments"
-      linters:
-        - gosec
-    # Looks like the match in "EXC0009" above doesn't catch this one
-    # TODO: consider upstreaming this to golangci-lint's default exclusion rules
-    - text: "G306: Expect WriteFile permissions to be 0600 or less"
-      linters:
-        - gosec
-
     # TODO: make sure all packages have a description. Currently, there's 67 packages without.
     - text: "package-comments: should have a package comment"
       linters:

Dockerfile

@@ -4,12 +4,12 @@ ARG BASE_VARIANT=alpine
 ARG ALPINE_VERSION=3.20
 ARG BASE_DEBIAN_DISTRO=bookworm
 
-ARG GO_VERSION=1.21.11
-ARG XX_VERSION=1.4.0
+ARG GO_VERSION=1.22.12
+ARG XX_VERSION=1.6.1
 ARG GOVERSIONINFO_VERSION=v1.3.0
 ARG GOTESTSUM_VERSION=v1.10.0
-ARG BUILDX_VERSION=0.15.1
-ARG COMPOSE_VERSION=v2.27.1
+ARG BUILDX_VERSION=0.20.0
+ARG COMPOSE_VERSION=v2.32.4
 
 FROM --platform=$BUILDPLATFORM tonistiigi/xx:${XX_VERSION} AS xx
 

Makefile

@@ -86,6 +86,16 @@ mod-outdated: ## check outdated dependencies
 authors: ## generate AUTHORS file from git history
 	scripts/docs/generate-authors.sh
 
+.PHONY: completion
+completion: binary
+completion: /etc/bash_completion.d/docker
+completion: ## generate and install the completion scripts
+
+.PHONY: /etc/bash_completion.d/docker
+/etc/bash_completion.d/docker: ## generate and install the bash-completion script
+	mkdir -p /etc/bash_completion.d
+	docker completion bash > /etc/bash_completion.d/docker
+
 .PHONY: manpages
 manpages: ## generate man pages from go source and markdown
 	scripts/docs/generate-man.sh

VERSION

@@ -1 +1 @@
-27.0.1-dev
+27.3.1-dev

cli-plugins/manager/candidate.go

@@ -17,5 +17,5 @@ func (c *candidate) Path() string {
 }
 
 func (c *candidate) Metadata() ([]byte, error) {
-	return exec.Command(c.path, MetadataSubcommandName).Output()
+	return exec.Command(c.path, MetadataSubcommandName).Output() // #nosec G204 -- ignore "Subprocess launched with a potential tainted input or cmd arguments"
 }

cli-plugins/manager/error.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package manager
 

cli-plugins/manager/manager.go

@@ -75,10 +75,12 @@ func getPluginDirs(cfg *configfile.ConfigFile) ([]string, error) {
 	return pluginDirs, nil
 }
 
-func addPluginCandidatesFromDir(res map[string][]string, d string) error {
+func addPluginCandidatesFromDir(res map[string][]string, d string) {
 	dentries, err := os.ReadDir(d)
+	// Silently ignore any directories which we cannot list (e.g. due to
+	// permissions or anything else) or which is not a directory
 	if err != nil {
-		return err
+		return
 	}
 	for _, dentry := range dentries {
 		switch dentry.Type() & os.ModeType {
@@ -99,28 +101,15 @@ func addPluginCandidatesFromDir(res map[string][]string, d string) error {
 		}
 		res[name] = append(res[name], filepath.Join(d, dentry.Name()))
 	}
-	return nil
 }
 
 // listPluginCandidates returns a map from plugin name to the list of (unvalidated) Candidates. The list is in descending order of priority.
-func listPluginCandidates(dirs []string) (map[string][]string, error) {
+func listPluginCandidates(dirs []string) map[string][]string {
 	result := make(map[string][]string)
 	for _, d := range dirs {
-		// Silently ignore any directories which we cannot
-		// Stat (e.g. due to permissions or anything else) or
-		// which is not a directory.
-		if fi, err := os.Stat(d); err != nil || !fi.IsDir() {
-			continue
-		}
-		if err := addPluginCandidatesFromDir(result, d); err != nil {
-			// Silently ignore paths which don't exist.
-			if os.IsNotExist(err) {
-				continue
-			}
-			return nil, err // Or return partial result?
-		}
+		addPluginCandidatesFromDir(result, d)
 	}
-	return result, nil
+	return result
 }
 
 // GetPlugin returns a plugin on the system by its name
@@ -130,11 +119,7 @@ func GetPlugin(name string, dockerCli command.Cli, rootcmd *cobra.Command) (*Plu
 		return nil, err
 	}
 
-	candidates, err := listPluginCandidates(pluginDirs)
-	if err != nil {
-		return nil, err
-	}
-
+	candidates := listPluginCandidates(pluginDirs)
 	if paths, ok := candidates[name]; ok {
 		if len(paths) == 0 {
 			return nil, errPluginNotFound(name)
@@ -160,10 +145,7 @@ func ListPlugins(dockerCli command.Cli, rootcmd *cobra.Command) ([]Plugin, error
 		return nil, err
 	}
 
-	candidates, err := listPluginCandidates(pluginDirs)
-	if err != nil {
-		return nil, err
-	}
+	candidates := listPluginCandidates(pluginDirs)
 
 	var plugins []Plugin
 	var mu sync.Mutex
@@ -240,7 +222,8 @@ func PluginRunCommand(dockerCli command.Cli, name string, rootcmd *cobra.Command
 			// TODO: why are we not returning plugin.Err?
 			return nil, errPluginNotFound(name)
 		}
-		cmd := exec.Command(plugin.Path, args...)
+		cmd := exec.Command(plugin.Path, args...) // #nosec G204 -- ignore "Subprocess launched with a potential tainted input or cmd arguments"
+
 		// Using dockerCli.{In,Out,Err}() here results in a hang until something is input.
 		// See: - https://github.com/golang/go/issues/10338
 		//      - https://github.com/golang/go/commit/d000e8742a173aa0659584aa01b7ba2834ba28ab

cli-plugins/manager/manager_test.go

@@ -51,8 +51,7 @@ func TestListPluginCandidates(t *testing.T) {
 		dirs = append(dirs, dir.Join(d))
 	}
 
-	candidates, err := listPluginCandidates(dirs)
-	assert.NilError(t, err)
+	candidates := listPluginCandidates(dirs)
 	exp := map[string][]string{
 		"plugin1": {
 			dir.Join("plugins1", "docker-plugin1"),
@@ -82,6 +81,29 @@ func TestListPluginCandidates(t *testing.T) {
 	assert.DeepEqual(t, candidates, exp)
 }
 
+// Regression test for https://github.com/docker/cli/issues/5643.
+// Check that inaccessible directories that come before accessible ones are ignored
+// and do not prevent the latter from being processed.
+func TestListPluginCandidatesInaccesibleDir(t *testing.T) {
+	dir := fs.NewDir(t, t.Name(),
+		fs.WithDir("no-perm", fs.WithMode(0)),
+		fs.WithDir("plugins",
+			fs.WithFile("docker-buildx", ""),
+		),
+	)
+	defer dir.Remove()
+
+	candidates := listPluginCandidates([]string{
+		dir.Join("no-perm"),
+		dir.Join("plugins"),
+	})
+	assert.DeepEqual(t, candidates, map[string][]string{
+		"buildx": {
+			dir.Join("plugins", "docker-buildx"),
+		},
+	})
+}
+
 func TestGetPlugin(t *testing.T) {
 	dir := fs.NewDir(t, t.Name(),
 		fs.WithFile("docker-bbb", `

cli-plugins/manager/plugin.go

@@ -112,7 +112,7 @@ func (p *Plugin) RunHook(ctx context.Context, hookData HookPluginData) ([]byte,
 		return nil, wrapAsPluginError(err, "failed to marshall hook data")
 	}
 
-	pCmd := exec.CommandContext(ctx, p.Path, p.Name, HookSubcommandName, string(hDataBytes))
+	pCmd := exec.CommandContext(ctx, p.Path, p.Name, HookSubcommandName, string(hDataBytes)) // #nosec G204 -- ignore "Subprocess launched with a potential tainted input or cmd arguments"
 	pCmd.Env = os.Environ()
 	pCmd.Env = append(pCmd.Env, ReexecEnvvar+"="+os.Args[0])
 	hookCmdOutput, err := pCmd.Output()

cli-plugins/plugin/plugin.go

@@ -45,6 +45,7 @@ func RunPlugin(dockerCli *command.DockerCli, plugin *cobra.Command, meta manager
 			if os.Getenv("DOCKER_CLI_PLUGIN_USE_DIAL_STDIO") != "" {
 				opts = append(opts, withPluginClientConn(plugin.Name()))
 			}
+			opts = append(opts, command.WithEnableGlobalMeterProvider(), command.WithEnableGlobalTracerProvider())
 			err = tcmd.Initialize(opts...)
 			ogRunE := cmd.RunE
 			if ogRunE == nil {

cli-plugins/socket/socket.go

@@ -95,6 +95,9 @@ func (pl *PluginServer) Addr() net.Addr {
 //
 // The error value is that of the underlying [net.Listner.Close] call.
 func (pl *PluginServer) Close() error {
+	if pl == nil {
+		return nil
+	}
 	logrus.Trace("Closing plugin server")
 	// Close connections first to ensure the connections get io.EOF instead
 	// of a connection reset.

cli-plugins/socket/socket_test.go

@@ -117,6 +117,18 @@ func TestPluginServer(t *testing.T) {
 		assert.NilError(t, err, "failed to dial returned server")
 		checkDirNoNewPluginServer(t)
 	})
+
+	t.Run("does not panic on Close if server is nil", func(t *testing.T) {
+		var srv *PluginServer
+		defer func() {
+			if r := recover(); r != nil {
+				t.Errorf("panicked on Close")
+			}
+		}()
+
+		err := srv.Close()
+		assert.NilError(t, err)
+	})
 }
 
 func checkDirNoNewPluginServer(t *testing.T) {

cli/command/builder/prune_test.go

@@ -3,6 +3,7 @@ package builder
 import (
 	"context"
 	"errors"
+	"io"
 	"testing"
 
 	"github.com/docker/cli/internal/test"
@@ -19,5 +20,7 @@ func TestBuilderPromptTermination(t *testing.T) {
 		},
 	})
 	cmd := NewPruneCommand(cli)
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	test.TerminatePrompt(ctx, t, cmd, cli)
 }

cli/command/checkpoint/create_test.go

@@ -42,6 +42,7 @@ func TestCheckpointCreateErrors(t *testing.T) {
 		cmd := newCreateCommand(cli)
 		cmd.SetArgs(tc.args)
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
 }

cli/command/checkpoint/list_test.go

@@ -42,6 +42,7 @@ func TestCheckpointListErrors(t *testing.T) {
 		cmd := newListCommand(cli)
 		cmd.SetArgs(tc.args)
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
 }

cli/command/checkpoint/remove_test.go

@@ -41,6 +41,7 @@ func TestCheckpointRemoveErrors(t *testing.T) {
 		cmd := newRemoveCommand(cli)
 		cmd.SetArgs(tc.args)
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
 }

cli/command/cli.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package command
 
@@ -92,6 +92,8 @@ type DockerCli struct {
 	// this may be replaced by explicitly passing a context to functions that
 	// need it.
 	baseCtx context.Context
+
+	enableGlobalMeter, enableGlobalTracer bool
 }
 
 // DefaultVersion returns api.defaultVersion.
@@ -184,9 +186,18 @@ func (cli *DockerCli) BuildKitEnabled() (bool, error) {
 	if _, ok := aliasMap["builder"]; ok {
 		return true, nil
 	}
-	// otherwise, assume BuildKit is enabled but
-	// not if wcow reported from server side
-	return cli.ServerInfo().OSType != "windows", nil
+
+	si := cli.ServerInfo()
+	if si.BuildkitVersion == types.BuilderBuildKit {
+		// The daemon advertised BuildKit as the preferred builder; this may
+		// be either a Linux daemon or a Windows daemon with experimental
+		// BuildKit support enabled.
+		return true, nil
+	}
+
+	// otherwise, assume BuildKit is enabled for Linux, but disabled for
+	// Windows / WCOW, which does not yet support BuildKit by default.
+	return si.OSType != "windows", nil
 }
 
 // HooksEnabled returns whether plugin hooks are enabled.
@@ -275,8 +286,12 @@ func (cli *DockerCli) Initialize(opts *cliflags.ClientOptions, ops ...CLIOption)
 	}
 
 	// TODO(krissetto): pass ctx to the funcs instead of using this
-	cli.createGlobalMeterProvider(cli.baseCtx)
-	cli.createGlobalTracerProvider(cli.baseCtx)
+	if cli.enableGlobalMeter {
+		cli.createGlobalMeterProvider(cli.baseCtx)
+	}
+	if cli.enableGlobalTracer {
+		cli.createGlobalTracerProvider(cli.baseCtx)
+	}
 
 	return nil
 }
@@ -309,7 +324,7 @@ func newAPIClientFromEndpoint(ep docker.Endpoint, configFile *configfile.ConfigF
 	if len(configFile.HTTPHeaders) > 0 {
 		opts = append(opts, client.WithHTTPHeaders(configFile.HTTPHeaders))
 	}
-	opts = append(opts, client.WithUserAgent(UserAgent()))
+	opts = append(opts, withCustomHeadersFromEnv(), client.WithUserAgent(UserAgent()))
 	return client.NewClientWithOpts(opts...)
 }
 

cli/command/cli_options.go

@@ -2,13 +2,18 @@ package command
 
 import (
 	"context"
+	"encoding/csv"
 	"io"
+	"net/http"
 	"os"
 	"strconv"
+	"strings"
 
 	"github.com/docker/cli/cli/streams"
 	"github.com/docker/docker/client"
+	"github.com/docker/docker/errdefs"
 	"github.com/moby/term"
+	"github.com/pkg/errors"
 )
 
 // CLIOption is a functional argument to apply options to a [DockerCli]. These
@@ -108,3 +113,107 @@ func WithAPIClient(c client.APIClient) CLIOption {
 		return nil
 	}
 }
+
+// envOverrideHTTPHeaders is the name of the environment-variable that can be
+// used to set custom HTTP headers to be sent by the client. This environment
+// variable is the equivalent to the HttpHeaders field in the configuration
+// file.
+//
+// WARNING: If both config and environment-variable are set, the environment
+// variable currently overrides all headers set in the configuration file.
+// This behavior may change in a future update, as we are considering the
+// environment variable to be appending to existing headers (and to only
+// override headers with the same name).
+//
+// While this env-var allows for custom headers to be set, it does not allow
+// for built-in headers (such as "User-Agent", if set) to be overridden.
+// Also see [client.WithHTTPHeaders] and [client.WithUserAgent].
+//
+// This environment variable can be used in situations where headers must be
+// set for a specific invocation of the CLI, but should not be set by default,
+// and therefore cannot be set in the config-file.
+//
+// envOverrideHTTPHeaders accepts a comma-separated (CSV) list of key=value pairs,
+// where key must be a non-empty, valid MIME header format. Whitespaces surrounding
+// the key are trimmed, and the key is normalised. Whitespaces in values are
+// preserved, but "key=value" pairs with an empty value (e.g. "key=") are ignored.
+// Tuples without a "=" produce an error.
+//
+// It follows CSV rules for escaping, allowing "key=value" pairs to be quoted
+// if they must contain commas, which allows for multiple values for a single
+// header to be set. If a key is repeated in the list, later values override
+// prior values.
+//
+// For example, the following value:
+//
+//	one=one-value,"two=two,value","three= a value with whitespace  ",four=,five=five=one,five=five-two
+//
+// Produces four headers (four is omitted as it has an empty value set):
+//
+// - one (value is "one-value")
+// - two (value is "two,value")
+// - three (value is " a value with whitespace  ")
+// - five (value is "five-two", the later value has overridden the prior value)
+const envOverrideHTTPHeaders = "DOCKER_CUSTOM_HEADERS"
+
+// withCustomHeadersFromEnv overriding custom HTTP headers to be sent by the
+// client through the [envOverrideHTTPHeaders] environment-variable. This
+// environment variable is the equivalent to the HttpHeaders field in the
+// configuration file.
+//
+// WARNING: If both config and environment-variable are set, the environment-
+// variable currently overrides all headers set in the configuration file.
+// This behavior may change in a future update, as we are considering the
+// environment-variable to be appending to existing headers (and to only
+// override headers with the same name).
+//
+// TODO(thaJeztah): this is a client Option, and should be moved to the client. It is non-exported for that reason.
+func withCustomHeadersFromEnv() client.Opt {
+	return func(apiClient *client.Client) error {
+		value := os.Getenv(envOverrideHTTPHeaders)
+		if value == "" {
+			return nil
+		}
+		csvReader := csv.NewReader(strings.NewReader(value))
+		fields, err := csvReader.Read()
+		if err != nil {
+			return errdefs.InvalidParameter(errors.Errorf("failed to parse custom headers from %s environment variable: value must be formatted as comma-separated key=value pairs", envOverrideHTTPHeaders))
+		}
+		if len(fields) == 0 {
+			return nil
+		}
+
+		env := map[string]string{}
+		for _, kv := range fields {
+			k, v, hasValue := strings.Cut(kv, "=")
+
+			// Only strip whitespace in keys; preserve whitespace in values.
+			k = strings.TrimSpace(k)
+
+			if k == "" {
+				return errdefs.InvalidParameter(errors.Errorf(`failed to set custom headers from %s environment variable: value contains a key=value pair with an empty key: '%s'`, envOverrideHTTPHeaders, kv))
+			}
+
+			// We don't currently allow empty key=value pairs, and produce an error.
+			// This is something we could allow in future (e.g. to read value
+			// from an environment variable with the same name). In the meantime,
+			// produce an error to prevent users from depending on this.
+			if !hasValue {
+				return errdefs.InvalidParameter(errors.Errorf(`failed to set custom headers from %s environment variable: missing "=" in key=value pair: '%s'`, envOverrideHTTPHeaders, kv))
+			}
+
+			env[http.CanonicalHeaderKey(k)] = v
+		}
+
+		if len(env) == 0 {
+			// We should probably not hit this case, as we don't skip values
+			// (only return errors), but we don't want to discard existing
+			// headers with an empty set.
+			return nil
+		}
+
+		// TODO(thaJeztah): add a client.WithExtraHTTPHeaders() function to allow these headers to be _added_ to existing ones, instead of _replacing_
+		//  see https://github.com/docker/cli/pull/5098#issuecomment-2147403871  (when updating, also update the WARNING in the function and env-var GoDoc)
+		return client.WithHTTPHeaders(env)(apiClient)
+	}
+}

cli/command/cli_test.go

@@ -87,6 +87,41 @@ func TestNewAPIClientFromFlagsWithCustomHeaders(t *testing.T) {
 	assert.DeepEqual(t, received, expectedHeaders)
 }
 
+func TestNewAPIClientFromFlagsWithCustomHeadersFromEnv(t *testing.T) {
+	var received http.Header
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		received = r.Header.Clone()
+		_, _ = w.Write([]byte("OK"))
+	}))
+	defer ts.Close()
+	host := strings.Replace(ts.URL, "http://", "tcp://", 1)
+	opts := &flags.ClientOptions{Hosts: []string{host}}
+	configFile := &configfile.ConfigFile{
+		HTTPHeaders: map[string]string{
+			"My-Header": "Custom-Value from config-file",
+		},
+	}
+
+	// envOverrideHTTPHeaders should override the HTTPHeaders from the config-file,
+	// so "My-Header" should not be present.
+	t.Setenv(envOverrideHTTPHeaders, `one=one-value,"two=two,value",three=,four=four-value,four=four-value-override`)
+	apiClient, err := NewAPIClientFromFlags(opts, configFile)
+	assert.NilError(t, err)
+	assert.Equal(t, apiClient.DaemonHost(), host)
+	assert.Equal(t, apiClient.ClientVersion(), api.DefaultVersion)
+
+	expectedHeaders := http.Header{
+		"One":        []string{"one-value"},
+		"Two":        []string{"two,value"},
+		"Three":      []string{""},
+		"Four":       []string{"four-value-override"},
+		"User-Agent": []string{UserAgent()},
+	}
+	_, err = apiClient.Ping(context.Background())
+	assert.NilError(t, err)
+	assert.DeepEqual(t, received, expectedHeaders)
+}
+
 func TestNewAPIClientFromFlagsWithAPIVersionFromEnv(t *testing.T) {
 	customVersion := "v3.3.3"
 	t.Setenv("DOCKER_API_VERSION", customVersion)

cli/command/completion/functions.go

@@ -2,6 +2,7 @@ package completion
 
 import (
 	"os"
+	"strings"
 
 	"github.com/docker/cli/cli/command/formatter"
 	"github.com/docker/docker/api/types"
@@ -59,7 +60,7 @@ func ContainerNames(dockerCLI APIClientProvider, all bool, filters ...func(types
 		for _, ctr := range list {
 			skip := false
 			for _, fn := range filters {
-				if !fn(ctr) {
+				if fn != nil && !fn(ctr) {
 					skip = true
 					break
 				}
@@ -106,7 +107,86 @@ func NetworkNames(dockerCLI APIClientProvider) ValidArgsFn {
 	}
 }
 
+// EnvVarNames offers completion for environment-variable names. This
+// completion can be used for "--env" and "--build-arg" flags, which
+// allow obtaining the value of the given environment-variable if present
+// in the local environment, so we only should complete the names of the
+// environment variables, and not their value. This also prevents the
+// completion script from printing values of environment variables
+// containing sensitive values.
+//
+// For example;
+//
+//	export MY_VAR=hello
+//	docker run --rm --env MY_VAR alpine printenv MY_VAR
+//	hello
+func EnvVarNames(_ *cobra.Command, _ []string, _ string) (names []string, _ cobra.ShellCompDirective) {
+	envs := os.Environ()
+	names = make([]string, 0, len(envs))
+	for _, env := range envs {
+		name, _, _ := strings.Cut(env, "=")
+		names = append(names, name)
+	}
+	return names, cobra.ShellCompDirectiveNoFileComp
+}
+
+// FromList offers completion for the given list of options.
+func FromList(options ...string) ValidArgsFn {
+	return cobra.FixedCompletions(options, cobra.ShellCompDirectiveNoFileComp)
+}
+
+// FileNames is a convenience function to use [cobra.ShellCompDirectiveDefault],
+// which indicates to let the shell perform its default behavior after
+// completions have been provided.
+func FileNames(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return nil, cobra.ShellCompDirectiveDefault
+}
+
 // NoComplete is used for commands where there's no relevant completion
 func NoComplete(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 	return nil, cobra.ShellCompDirectiveNoFileComp
 }
+
+var commonPlatforms = []string{
+	"linux",
+	"linux/386",
+	"linux/amd64",
+	"linux/arm",
+	"linux/arm/v5",
+	"linux/arm/v6",
+	"linux/arm/v7",
+	"linux/arm64",
+	"linux/arm64/v8",
+
+	// IBM power and z platforms
+	"linux/ppc64le",
+	"linux/s390x",
+
+	// Not yet supported
+	"linux/riscv64",
+
+	"windows",
+	"windows/amd64",
+
+	"wasip1",
+	"wasip1/wasm",
+}
+
+// Platforms offers completion for platform-strings. It provides a non-exhaustive
+// list of platforms to be used for completion. Platform-strings are based on
+// [runtime.GOOS] and [runtime.GOARCH], but with (optional) variants added. A
+// list of recognised os/arch combinations from the Go runtime can be obtained
+// through "go tool dist list".
+//
+// Some noteworthy exclusions from this list:
+//
+//   - arm64 images ("windows/arm64", "windows/arm64/v8") do not yet exist for windows.
+//   - we don't (yet) include `os-variant` for completion (as can be used for Windows images)
+//   - we don't (yet) include platforms for which we don't build binaries, such as
+//     BSD platforms (freebsd, netbsd, openbsd), android, macOS (darwin).
+//   - we currently exclude architectures that may have unofficial builds,
+//     but don't have wide adoption (and no support), such as loong64, mipsXXX,
+//     ppc64 (non-le) to prevent confusion.
+func Platforms(_ *cobra.Command, _ []string, _ string) (platforms []string, _ cobra.ShellCompDirective) {
+	return commonPlatforms, cobra.ShellCompDirectiveNoFileComp
+}

cli/command/completion/functions_test.go

@@ -0,0 +1,351 @@
+package completion
+
+import (
+	"context"
+	"errors"
+	"sort"
+	"testing"
+
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/api/types/network"
+	"github.com/docker/docker/api/types/volume"
+	"github.com/docker/docker/client"
+	"github.com/google/go-cmp/cmp/cmpopts"
+	"github.com/spf13/cobra"
+	"gotest.tools/v3/assert"
+	is "gotest.tools/v3/assert/cmp"
+	"gotest.tools/v3/env"
+)
+
+type fakeCLI struct {
+	*fakeClient
+}
+
+// Client implements [APIClientProvider].
+func (c fakeCLI) Client() client.APIClient {
+	return c.fakeClient
+}
+
+type fakeClient struct {
+	client.Client
+	containerListFunc func(options container.ListOptions) ([]types.Container, error)
+	imageListFunc     func(options image.ListOptions) ([]image.Summary, error)
+	networkListFunc   func(ctx context.Context, options network.ListOptions) ([]network.Summary, error)
+	volumeListFunc    func(filter filters.Args) (volume.ListResponse, error)
+}
+
+func (c *fakeClient) ContainerList(_ context.Context, options container.ListOptions) ([]types.Container, error) {
+	if c.containerListFunc != nil {
+		return c.containerListFunc(options)
+	}
+	return []types.Container{}, nil
+}
+
+func (c *fakeClient) ImageList(_ context.Context, options image.ListOptions) ([]image.Summary, error) {
+	if c.imageListFunc != nil {
+		return c.imageListFunc(options)
+	}
+	return []image.Summary{}, nil
+}
+
+func (c *fakeClient) NetworkList(ctx context.Context, options network.ListOptions) ([]network.Summary, error) {
+	if c.networkListFunc != nil {
+		return c.networkListFunc(ctx, options)
+	}
+	return []network.Inspect{}, nil
+}
+
+func (c *fakeClient) VolumeList(_ context.Context, options volume.ListOptions) (volume.ListResponse, error) {
+	if c.volumeListFunc != nil {
+		return c.volumeListFunc(options.Filters)
+	}
+	return volume.ListResponse{}, nil
+}
+
+func TestCompleteContainerNames(t *testing.T) {
+	tests := []struct {
+		doc              string
+		showAll, showIDs bool
+		filters          []func(types.Container) bool
+		containers       []types.Container
+		expOut           []string
+		expOpts          container.ListOptions
+		expDirective     cobra.ShellCompDirective
+	}{
+		{
+			doc:          "no results",
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:     "all containers",
+			showAll: true,
+			containers: []types.Container{
+				{ID: "id-c", State: "running", Names: []string{"/container-c", "/container-c/link-b"}},
+				{ID: "id-b", State: "created", Names: []string{"/container-b"}},
+				{ID: "id-a", State: "exited", Names: []string{"/container-a"}},
+			},
+			expOut:       []string{"container-c", "container-c/link-b", "container-b", "container-a"},
+			expOpts:      container.ListOptions{All: true},
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:     "all containers with ids",
+			showAll: true,
+			showIDs: true,
+			containers: []types.Container{
+				{ID: "id-c", State: "running", Names: []string{"/container-c", "/container-c/link-b"}},
+				{ID: "id-b", State: "created", Names: []string{"/container-b"}},
+				{ID: "id-a", State: "exited", Names: []string{"/container-a"}},
+			},
+			expOut:       []string{"id-c", "container-c", "container-c/link-b", "id-b", "container-b", "id-a", "container-a"},
+			expOpts:      container.ListOptions{All: true},
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:     "only running containers",
+			showAll: false,
+			containers: []types.Container{
+				{ID: "id-c", State: "running", Names: []string{"/container-c", "/container-c/link-b"}},
+			},
+			expOut:       []string{"container-c", "container-c/link-b"},
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:     "with filter",
+			showAll: true,
+			filters: []func(types.Container) bool{
+				func(container types.Container) bool { return container.State == "created" },
+			},
+			containers: []types.Container{
+				{ID: "id-c", State: "running", Names: []string{"/container-c", "/container-c/link-b"}},
+				{ID: "id-b", State: "created", Names: []string{"/container-b"}},
+				{ID: "id-a", State: "exited", Names: []string{"/container-a"}},
+			},
+			expOut:       []string{"container-b"},
+			expOpts:      container.ListOptions{All: true},
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:     "multiple filters",
+			showAll: true,
+			filters: []func(types.Container) bool{
+				func(container types.Container) bool { return container.ID == "id-a" },
+				func(container types.Container) bool { return container.State == "created" },
+			},
+			containers: []types.Container{
+				{ID: "id-c", State: "running", Names: []string{"/container-c", "/container-c/link-b"}},
+				{ID: "id-b", State: "created", Names: []string{"/container-b"}},
+				{ID: "id-a", State: "created", Names: []string{"/container-a"}},
+			},
+			expOut:       []string{"container-a"},
+			expOpts:      container.ListOptions{All: true},
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:          "with error",
+			expDirective: cobra.ShellCompDirectiveError,
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.doc, func(t *testing.T) {
+			if tc.showIDs {
+				t.Setenv("DOCKER_COMPLETION_SHOW_CONTAINER_IDS", "yes")
+			}
+			comp := ContainerNames(fakeCLI{&fakeClient{
+				containerListFunc: func(opts container.ListOptions) ([]types.Container, error) {
+					assert.Check(t, is.DeepEqual(opts, tc.expOpts, cmpopts.IgnoreUnexported(container.ListOptions{}, filters.Args{})))
+					if tc.expDirective == cobra.ShellCompDirectiveError {
+						return nil, errors.New("some error occurred")
+					}
+					return tc.containers, nil
+				},
+			}}, tc.showAll, tc.filters...)
+
+			containers, directives := comp(&cobra.Command{}, nil, "")
+			assert.Check(t, is.Equal(directives&tc.expDirective, tc.expDirective))
+			assert.Check(t, is.DeepEqual(containers, tc.expOut))
+		})
+	}
+}
+
+func TestCompleteEnvVarNames(t *testing.T) {
+	env.PatchAll(t, map[string]string{
+		"ENV_A": "hello-a",
+		"ENV_B": "hello-b",
+	})
+	values, directives := EnvVarNames(nil, nil, "")
+	assert.Check(t, is.Equal(directives&cobra.ShellCompDirectiveNoFileComp, cobra.ShellCompDirectiveNoFileComp), "Should not perform file completion")
+
+	sort.Strings(values)
+	expected := []string{"ENV_A", "ENV_B"}
+	assert.Check(t, is.DeepEqual(values, expected))
+}
+
+func TestCompleteFileNames(t *testing.T) {
+	values, directives := FileNames(nil, nil, "")
+	assert.Check(t, is.Equal(directives, cobra.ShellCompDirectiveDefault))
+	assert.Check(t, is.Len(values, 0))
+}
+
+func TestCompleteFromList(t *testing.T) {
+	expected := []string{"one", "two", "three"}
+
+	values, directives := FromList(expected...)(nil, nil, "")
+	assert.Check(t, is.Equal(directives&cobra.ShellCompDirectiveNoFileComp, cobra.ShellCompDirectiveNoFileComp), "Should not perform file completion")
+	assert.Check(t, is.DeepEqual(values, expected))
+}
+
+func TestCompleteImageNames(t *testing.T) {
+	tests := []struct {
+		doc          string
+		images       []image.Summary
+		expOut       []string
+		expDirective cobra.ShellCompDirective
+	}{
+		{
+			doc:          "no results",
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc: "with results",
+			images: []image.Summary{
+				{RepoTags: []string{"image-c:latest", "image-c:other"}},
+				{RepoTags: []string{"image-b:latest", "image-b:other"}},
+				{RepoTags: []string{"image-a:latest", "image-a:other"}},
+			},
+			expOut:       []string{"image-c:latest", "image-c:other", "image-b:latest", "image-b:other", "image-a:latest", "image-a:other"},
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:          "with error",
+			expDirective: cobra.ShellCompDirectiveError,
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.doc, func(t *testing.T) {
+			comp := ImageNames(fakeCLI{&fakeClient{
+				imageListFunc: func(options image.ListOptions) ([]image.Summary, error) {
+					if tc.expDirective == cobra.ShellCompDirectiveError {
+						return nil, errors.New("some error occurred")
+					}
+					return tc.images, nil
+				},
+			}})
+
+			volumes, directives := comp(&cobra.Command{}, nil, "")
+			assert.Check(t, is.Equal(directives&tc.expDirective, tc.expDirective))
+			assert.Check(t, is.DeepEqual(volumes, tc.expOut))
+		})
+	}
+}
+
+func TestCompleteNetworkNames(t *testing.T) {
+	tests := []struct {
+		doc          string
+		networks     []network.Summary
+		expOut       []string
+		expDirective cobra.ShellCompDirective
+	}{
+		{
+			doc:          "no results",
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc: "with results",
+			networks: []network.Summary{
+				{ID: "nw-c", Name: "network-c"},
+				{ID: "nw-b", Name: "network-b"},
+				{ID: "nw-a", Name: "network-a"},
+			},
+			expOut:       []string{"network-c", "network-b", "network-a"},
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:          "with error",
+			expDirective: cobra.ShellCompDirectiveError,
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.doc, func(t *testing.T) {
+			comp := NetworkNames(fakeCLI{&fakeClient{
+				networkListFunc: func(ctx context.Context, options network.ListOptions) ([]network.Summary, error) {
+					if tc.expDirective == cobra.ShellCompDirectiveError {
+						return nil, errors.New("some error occurred")
+					}
+					return tc.networks, nil
+				},
+			}})
+
+			volumes, directives := comp(&cobra.Command{}, nil, "")
+			assert.Check(t, is.Equal(directives&tc.expDirective, tc.expDirective))
+			assert.Check(t, is.DeepEqual(volumes, tc.expOut))
+		})
+	}
+}
+
+func TestCompleteNoComplete(t *testing.T) {
+	values, directives := NoComplete(nil, nil, "")
+	assert.Check(t, is.Equal(directives, cobra.ShellCompDirectiveNoFileComp))
+	assert.Check(t, is.Len(values, 0))
+}
+
+func TestCompletePlatforms(t *testing.T) {
+	values, directives := Platforms(nil, nil, "")
+	assert.Check(t, is.Equal(directives&cobra.ShellCompDirectiveNoFileComp, cobra.ShellCompDirectiveNoFileComp), "Should not perform file completion")
+	assert.Check(t, is.DeepEqual(values, commonPlatforms))
+}
+
+func TestCompleteVolumeNames(t *testing.T) {
+	tests := []struct {
+		doc          string
+		volumes      []*volume.Volume
+		expOut       []string
+		expDirective cobra.ShellCompDirective
+	}{
+		{
+			doc:          "no results",
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc: "with results",
+			volumes: []*volume.Volume{
+				{Name: "volume-c"},
+				{Name: "volume-b"},
+				{Name: "volume-a"},
+			},
+			expOut:       []string{"volume-c", "volume-b", "volume-a"},
+			expDirective: cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			doc:          "with error",
+			expDirective: cobra.ShellCompDirectiveError,
+		},
+	}
+
+	for _, tc := range tests {
+		tc := tc
+		t.Run(tc.doc, func(t *testing.T) {
+			comp := VolumeNames(fakeCLI{&fakeClient{
+				volumeListFunc: func(filter filters.Args) (volume.ListResponse, error) {
+					if tc.expDirective == cobra.ShellCompDirectiveError {
+						return volume.ListResponse{}, errors.New("some error occurred")
+					}
+					return volume.ListResponse{Volumes: tc.volumes}, nil
+				},
+			}})
+
+			volumes, directives := comp(&cobra.Command{}, nil, "")
+			assert.Check(t, is.Equal(directives&tc.expDirective, tc.expDirective))
+			assert.Check(t, is.DeepEqual(volumes, tc.expOut))
+		})
+	}
+}

cli/command/config/create_test.go

@@ -43,14 +43,18 @@ func TestConfigCreateErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cmd := newConfigCreateCommand(
-			test.NewFakeCli(&fakeClient{
-				configCreateFunc: tc.configCreateFunc,
-			}),
-		)
-		cmd.SetArgs(tc.args)
-		cmd.SetOut(io.Discard)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.expectedError, func(t *testing.T) {
+			cmd := newConfigCreateCommand(
+				test.NewFakeCli(&fakeClient{
+					configCreateFunc: tc.configCreateFunc,
+				}),
+			)
+			cmd.SetArgs(tc.args)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 

cli/command/config/inspect.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package config
 

cli/command/config/inspect_test.go

@@ -61,6 +61,7 @@ func TestConfigInspectErrors(t *testing.T) {
 			assert.Check(t, cmd.Flags().Set(key, value))
 		}
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
 }

cli/command/config/ls_test.go

@@ -42,6 +42,7 @@ func TestConfigListErrors(t *testing.T) {
 		)
 		cmd.SetArgs(tc.args)
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
 }

cli/command/config/remove_test.go

@@ -37,6 +37,7 @@ func TestConfigRemoveErrors(t *testing.T) {
 		)
 		cmd.SetArgs(tc.args)
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
 }
@@ -74,6 +75,7 @@ func TestConfigRemoveContinueAfterError(t *testing.T) {
 	cmd := newConfigRemoveCommand(cli)
 	cmd.SetArgs(names)
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	assert.Error(t, cmd.Execute(), "error removing config: foo")
 	assert.Check(t, is.DeepEqual(names, removedConfigs))
 }

cli/command/container/attach.go

@@ -73,7 +73,8 @@ func RunAttach(ctx context.Context, dockerCLI command.Cli, containerID string, o
 	apiClient := dockerCLI.Client()
 
 	// request channel to wait for client
-	resultC, errC := apiClient.ContainerWait(ctx, containerID, "")
+	waitCtx := context.WithoutCancel(ctx)
+	resultC, errC := apiClient.ContainerWait(waitCtx, containerID, "")
 
 	c, err := inspectContainerAndCheckState(ctx, apiClient, containerID)
 	if err != nil {
@@ -146,7 +147,8 @@ func RunAttach(ctx context.Context, dockerCLI command.Cli, containerID string, o
 		detachKeys:   options.DetachKeys,
 	}
 
-	if err := streamer.stream(ctx); err != nil {
+	// if the context was canceled, this was likely intentional and we shouldn't return an error
+	if err := streamer.stream(ctx); err != nil && !errors.Is(err, context.Canceled) {
 		return err
 	}
 
@@ -163,6 +165,9 @@ func getExitStatus(errC <-chan error, resultC <-chan container.WaitResponse) err
 			return cli.StatusError{StatusCode: int(result.StatusCode)}
 		}
 	case err := <-errC:
+		if errors.Is(err, context.Canceled) {
+			return nil
+		}
 		return err
 	}
 

cli/command/container/attach_test.go

@@ -1,6 +1,7 @@
 package container
 
 import (
+	"context"
 	"io"
 	"testing"
 
@@ -69,19 +70,19 @@ func TestNewAttachCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cmd := NewAttachCommand(test.NewFakeCli(&fakeClient{inspectFunc: tc.containerInspectFunc}))
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := NewAttachCommand(test.NewFakeCli(&fakeClient{inspectFunc: tc.containerInspectFunc}))
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 
 func TestGetExitStatus(t *testing.T) {
-	var (
-		expectedErr = errors.New("unexpected error")
-		errC        = make(chan error, 1)
-		resultC     = make(chan container.WaitResponse, 1)
-	)
+	expectedErr := errors.New("unexpected error")
 
 	testcases := []struct {
 		result        *container.WaitResponse
@@ -109,16 +110,24 @@ func TestGetExitStatus(t *testing.T) {
 			},
 			expectedError: cli.StatusError{StatusCode: 15},
 		},
+		{
+			err:           context.Canceled,
+			expectedError: nil,
+		},
 	}
 
 	for _, testcase := range testcases {
+		errC := make(chan error, 1)
+		resultC := make(chan container.WaitResponse, 1)
 		if testcase.err != nil {
 			errC <- testcase.err
 		}
 		if testcase.result != nil {
 			resultC <- *testcase.result
 		}
+
 		err := getExitStatus(errC, resultC)
+
 		if testcase.expectedError == nil {
 			assert.NilError(t, err)
 		} else {

cli/command/container/client_test.go

@@ -25,7 +25,7 @@ type fakeClient struct {
 		platform *specs.Platform,
 		containerName string) (container.CreateResponse, error)
 	containerStartFunc      func(containerID string, options container.StartOptions) error
-	imageCreateFunc         func(parentReference string, options image.CreateOptions) (io.ReadCloser, error)
+	imageCreateFunc         func(ctx context.Context, parentReference string, options image.CreateOptions) (io.ReadCloser, error)
 	infoFunc                func() (system.Info, error)
 	containerStatPathFunc   func(containerID, path string) (container.PathStat, error)
 	containerCopyFromFunc   func(containerID, srcPath string) (io.ReadCloser, container.PathStat, error)
@@ -94,9 +94,9 @@ func (f *fakeClient) ContainerRemove(ctx context.Context, containerID string, op
 	return nil
 }
 
-func (f *fakeClient) ImageCreate(_ context.Context, parentReference string, options image.CreateOptions) (io.ReadCloser, error) {
+func (f *fakeClient) ImageCreate(ctx context.Context, parentReference string, options image.CreateOptions) (io.ReadCloser, error) {
 	if f.imageCreateFunc != nil {
-		return f.imageCreateFunc(parentReference, options)
+		return f.imageCreateFunc(ctx, parentReference, options)
 	}
 	return nil, nil
 }

cli/command/container/completion.go

@@ -0,0 +1,336 @@
+// FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
+//go:build go1.22
+// +build go1.22
+
+package container
+
+import (
+	"strings"
+	"sync"
+
+	"github.com/docker/cli/cli/command/completion"
+	"github.com/docker/docker/api/types/container"
+	"github.com/moby/sys/capability"
+	"github.com/moby/sys/signal"
+	"github.com/spf13/cobra"
+)
+
+// allCaps is the magic value for "all capabilities".
+const allCaps = "ALL"
+
+// allLinuxCapabilities is a list of all known Linux capabilities.
+//
+// TODO(thaJeztah): add descriptions, and enable descriptions for our completion scripts (cobra.CompletionOptions.DisableDescriptions is currently set to "true")
+// TODO(thaJeztah): consider what casing we want to use for completion (see below);
+//
+// We need to consider what format is most convenient; currently we use the
+// canonical name (uppercase and "CAP_" prefix), however, tab-completion is
+// case-sensitive by default, so requires the user to type uppercase letters
+// to filter the list of options.
+//
+// Bash completion provides a `completion-ignore-case on` option to make completion
+// case-insensitive (https://askubuntu.com/a/87066), but it looks to be a global
+// option; the current cobra.CompletionOptions also don't provide this as an option
+// to be used in the generated completion-script.
+//
+// Fish completion has `smartcase` (by default?) which matches any case if
+// all of the input is lowercase.
+//
+// Zsh does not appear have a dedicated option, but allows setting matching-rules
+// (see https://superuser.com/a/1092328).
+var allLinuxCapabilities = sync.OnceValue(func() []string {
+	caps := capability.ListKnown()
+	out := make([]string, 0, len(caps)+1)
+	out = append(out, allCaps)
+	for _, c := range caps {
+		out = append(out, "CAP_"+strings.ToUpper(c.String()))
+	}
+	return out
+})
+
+// logDriverOptions provides the options for each built-in logging driver.
+var logDriverOptions = map[string][]string{
+	"awslogs": {
+		"max-buffer-size", "mode", "awslogs-create-group", "awslogs-credentials-endpoint", "awslogs-datetime-format",
+		"awslogs-group", "awslogs-multiline-pattern", "awslogs-region", "awslogs-stream", "tag",
+	},
+	"fluentd": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "fluentd-address", "fluentd-async",
+		"fluentd-buffer-limit", "fluentd-request-ack", "fluentd-retry-wait", "fluentd-max-retries",
+		"fluentd-sub-second-precision", "tag",
+	},
+	"gcplogs": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "gcp-log-cmd", "gcp-meta-id", "gcp-meta-name",
+		"gcp-meta-zone", "gcp-project",
+	},
+	"gelf": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "gelf-address", "gelf-compression-level",
+		"gelf-compression-type", "gelf-tcp-max-reconnect", "gelf-tcp-reconnect-delay", "tag",
+	},
+	"journald":  {"max-buffer-size", "mode", "env", "env-regex", "labels", "tag"},
+	"json-file": {"max-buffer-size", "mode", "env", "env-regex", "labels", "compress", "max-file", "max-size"},
+	"local":     {"max-buffer-size", "mode", "compress", "max-file", "max-size"},
+	"none":      {},
+	"splunk": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "splunk-caname", "splunk-capath", "splunk-format",
+		"splunk-gzip", "splunk-gzip-level", "splunk-index", "splunk-insecureskipverify", "splunk-source",
+		"splunk-sourcetype", "splunk-token", "splunk-url", "splunk-verify-connection", "tag",
+	},
+	"syslog": {
+		"max-buffer-size", "mode", "env", "env-regex", "labels", "syslog-address", "syslog-facility", "syslog-format",
+		"syslog-tls-ca-cert", "syslog-tls-cert", "syslog-tls-key", "syslog-tls-skip-verify", "tag",
+	},
+}
+
+// builtInLogDrivers provides a list of the built-in logging drivers.
+var builtInLogDrivers = sync.OnceValue(func() []string {
+	drivers := make([]string, 0, len(logDriverOptions))
+	for driver := range logDriverOptions {
+		drivers = append(drivers, driver)
+	}
+	return drivers
+})
+
+// allLogDriverOptions provides all options of the built-in logging drivers.
+// The list does not contain duplicates.
+var allLogDriverOptions = sync.OnceValue(func() []string {
+	var result []string
+	seen := make(map[string]bool)
+	for driver := range logDriverOptions {
+		for _, opt := range logDriverOptions[driver] {
+			if !seen[opt] {
+				seen[opt] = true
+				result = append(result, opt)
+			}
+		}
+	}
+	return result
+})
+
+// restartPolicies is a list of all valid restart-policies..
+//
+// TODO(thaJeztah): add descriptions, and enable descriptions for our completion scripts (cobra.CompletionOptions.DisableDescriptions is currently set to "true")
+var restartPolicies = []string{
+	string(container.RestartPolicyDisabled),
+	string(container.RestartPolicyAlways),
+	string(container.RestartPolicyOnFailure),
+	string(container.RestartPolicyUnlessStopped),
+}
+
+// addCompletions adds the completions that `run` and `create` have in common.
+func addCompletions(cmd *cobra.Command, dockerCLI completion.APIClientProvider) {
+	_ = cmd.RegisterFlagCompletionFunc("attach", completion.FromList("stderr", "stdin", "stdout"))
+	_ = cmd.RegisterFlagCompletionFunc("cap-add", completeLinuxCapabilityNames)
+	_ = cmd.RegisterFlagCompletionFunc("cap-drop", completeLinuxCapabilityNames)
+	_ = cmd.RegisterFlagCompletionFunc("cgroupns", completeCgroupns())
+	_ = cmd.RegisterFlagCompletionFunc("env", completion.EnvVarNames)
+	_ = cmd.RegisterFlagCompletionFunc("env-file", completion.FileNames)
+	_ = cmd.RegisterFlagCompletionFunc("ipc", completeIpc(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("link", completeLink(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("log-driver", completeLogDriver(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("log-opt", completeLogOpt)
+	_ = cmd.RegisterFlagCompletionFunc("network", completion.NetworkNames(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("pid", completePid(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
+	_ = cmd.RegisterFlagCompletionFunc("pull", completion.FromList(PullImageAlways, PullImageMissing, PullImageNever))
+	_ = cmd.RegisterFlagCompletionFunc("restart", completeRestartPolicies)
+	_ = cmd.RegisterFlagCompletionFunc("security-opt", completeSecurityOpt)
+	_ = cmd.RegisterFlagCompletionFunc("stop-signal", completeSignals)
+	_ = cmd.RegisterFlagCompletionFunc("storage-opt", completeStorageOpt)
+	_ = cmd.RegisterFlagCompletionFunc("ulimit", completeUlimit)
+	_ = cmd.RegisterFlagCompletionFunc("userns", completion.FromList("host"))
+	_ = cmd.RegisterFlagCompletionFunc("uts", completion.FromList("host"))
+	_ = cmd.RegisterFlagCompletionFunc("volume-driver", completeVolumeDriver(dockerCLI))
+	_ = cmd.RegisterFlagCompletionFunc("volumes-from", completion.ContainerNames(dockerCLI, true))
+}
+
+// completeCgroupns implements shell completion for the `--cgroupns` option of `run` and `create`.
+func completeCgroupns() completion.ValidArgsFn {
+	return completion.FromList(string(container.CgroupnsModeHost), string(container.CgroupnsModePrivate))
+}
+
+// completeDetachKeys implements shell completion for the `--detach-keys` option of `run` and `create`.
+func completeDetachKeys(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return []string{"ctrl-"}, cobra.ShellCompDirectiveNoSpace
+}
+
+// completeIpc implements shell completion for the `--ipc` option of `run` and `create`.
+// The completion is partly composite.
+func completeIpc(dockerCLI completion.APIClientProvider) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		if len(toComplete) > 0 && strings.HasPrefix("container", toComplete) { //nolint:gocritic // not swapped, matches partly typed "container"
+			return []string{"container:"}, cobra.ShellCompDirectiveNoSpace
+		}
+		if strings.HasPrefix(toComplete, "container:") {
+			names, _ := completion.ContainerNames(dockerCLI, true)(cmd, args, toComplete)
+			return prefixWith("container:", names), cobra.ShellCompDirectiveNoFileComp
+		}
+		return []string{
+			string(container.IPCModeContainer + ":"),
+			string(container.IPCModeHost),
+			string(container.IPCModeNone),
+			string(container.IPCModePrivate),
+			string(container.IPCModeShareable),
+		}, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
+// completeLink implements shell completion for the `--link` option  of `run` and `create`.
+func completeLink(dockerCLI completion.APIClientProvider) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		return postfixWith(":", containerNames(dockerCLI, cmd, args, toComplete)), cobra.ShellCompDirectiveNoSpace
+	}
+}
+
+// completeLogDriver implements shell completion for the `--log-driver` option  of `run` and `create`.
+// The log drivers are collected from a call to the Info endpoint with a fallback to a hard-coded list
+// of the build-in log drivers.
+func completeLogDriver(dockerCLI completion.APIClientProvider) completion.ValidArgsFn {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		info, err := dockerCLI.Client().Info(cmd.Context())
+		if err != nil {
+			return builtInLogDrivers(), cobra.ShellCompDirectiveNoFileComp
+		}
+		drivers := info.Plugins.Log
+		return drivers, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
+// completeLogOpt implements shell completion for the `--log-opt` option  of `run` and `create`.
+// If the user supplied a log-driver, only options for that driver are returned.
+func completeLogOpt(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	driver, _ := cmd.Flags().GetString("log-driver")
+	if options, exists := logDriverOptions[driver]; exists {
+		return postfixWith("=", options), cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp
+	}
+	return postfixWith("=", allLogDriverOptions()), cobra.ShellCompDirectiveNoSpace
+}
+
+// completePid implements shell completion for the `--pid` option  of `run` and `create`.
+func completePid(dockerCLI completion.APIClientProvider) func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+		if len(toComplete) > 0 && strings.HasPrefix("container", toComplete) { //nolint:gocritic // not swapped, matches partly typed "container"
+			return []string{"container:"}, cobra.ShellCompDirectiveNoSpace
+		}
+		if strings.HasPrefix(toComplete, "container:") {
+			names, _ := completion.ContainerNames(dockerCLI, true)(cmd, args, toComplete)
+			return prefixWith("container:", names), cobra.ShellCompDirectiveNoFileComp
+		}
+		return []string{"container:", "host"}, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
+// completeSecurityOpt implements shell completion for the `--security-opt` option of `run` and `create`.
+// The completion is partly composite.
+func completeSecurityOpt(_ *cobra.Command, _ []string, toComplete string) ([]string, cobra.ShellCompDirective) {
+	if len(toComplete) > 0 && strings.HasPrefix("apparmor=", toComplete) { //nolint:gocritic // not swapped, matches partly typed "apparmor="
+		return []string{"apparmor="}, cobra.ShellCompDirectiveNoSpace
+	}
+	if len(toComplete) > 0 && strings.HasPrefix("label", toComplete) { //nolint:gocritic // not swapped, matches partly typed "label"
+		return []string{"label="}, cobra.ShellCompDirectiveNoSpace
+	}
+	if strings.HasPrefix(toComplete, "label=") {
+		if strings.HasPrefix(toComplete, "label=d") {
+			return []string{"label=disable"}, cobra.ShellCompDirectiveNoFileComp
+		}
+		labels := []string{"disable", "level:", "role:", "type:", "user:"}
+		return prefixWith("label=", labels), cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp
+	}
+	// length must be > 1 here so that completion of "s" falls through.
+	if len(toComplete) > 1 && strings.HasPrefix("seccomp", toComplete) { //nolint:gocritic // not swapped, matches partly typed "seccomp"
+		return []string{"seccomp="}, cobra.ShellCompDirectiveNoSpace
+	}
+	if strings.HasPrefix(toComplete, "seccomp=") {
+		return []string{"seccomp=unconfined"}, cobra.ShellCompDirectiveNoFileComp
+	}
+	return []string{"apparmor=", "label=", "no-new-privileges", "seccomp=", "systempaths=unconfined"}, cobra.ShellCompDirectiveNoFileComp
+}
+
+// completeStorageOpt implements shell completion for the `--storage-opt` option  of `run` and `create`.
+func completeStorageOpt(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return []string{"size="}, cobra.ShellCompDirectiveNoSpace
+}
+
+// completeUlimit implements shell completion for the `--ulimit` option of `run` and `create`.
+func completeUlimit(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	limits := []string{
+		"as",
+		"chroot",
+		"core",
+		"cpu",
+		"data",
+		"fsize",
+		"locks",
+		"maxlogins",
+		"maxsyslogins",
+		"memlock",
+		"msgqueue",
+		"nice",
+		"nofile",
+		"nproc",
+		"priority",
+		"rss",
+		"rtprio",
+		"sigpending",
+		"stack",
+	}
+	return postfixWith("=", limits), cobra.ShellCompDirectiveNoSpace
+}
+
+// completeVolumeDriver contacts the API to get the built-in and installed volume drivers.
+func completeVolumeDriver(dockerCLI completion.APIClientProvider) completion.ValidArgsFn {
+	return func(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+		info, err := dockerCLI.Client().Info(cmd.Context())
+		if err != nil {
+			// fallback: the built-in drivers
+			return []string{"local"}, cobra.ShellCompDirectiveNoFileComp
+		}
+		drivers := info.Plugins.Volume
+		return drivers, cobra.ShellCompDirectiveNoFileComp
+	}
+}
+
+// containerNames contacts the API to get names and optionally IDs of containers.
+// In case of an error, an empty list is returned.
+func containerNames(dockerCLI completion.APIClientProvider, cmd *cobra.Command, args []string, toComplete string) []string {
+	names, _ := completion.ContainerNames(dockerCLI, true)(cmd, args, toComplete)
+	if names == nil {
+		return []string{}
+	}
+	return names
+}
+
+// prefixWith prefixes every element in the slice with the given prefix.
+func prefixWith(prefix string, values []string) []string {
+	result := make([]string, len(values))
+	for i, v := range values {
+		result[i] = prefix + v
+	}
+	return result
+}
+
+// postfixWith appends postfix to every element in the slice.
+func postfixWith(postfix string, values []string) []string {
+	result := make([]string, len(values))
+	for i, v := range values {
+		result[i] = v + postfix
+	}
+	return result
+}
+
+func completeLinuxCapabilityNames(cmd *cobra.Command, args []string, toComplete string) (names []string, _ cobra.ShellCompDirective) {
+	return completion.FromList(allLinuxCapabilities()...)(cmd, args, toComplete)
+}
+
+func completeRestartPolicies(cmd *cobra.Command, args []string, toComplete string) (names []string, _ cobra.ShellCompDirective) {
+	return completion.FromList(restartPolicies...)(cmd, args, toComplete)
+}
+
+func completeSignals(cmd *cobra.Command, args []string, toComplete string) (names []string, _ cobra.ShellCompDirective) {
+	// TODO(thaJeztah): do we want to provide the full list here, or a subset?
+	signalNames := make([]string, 0, len(signal.SignalMap))
+	for k := range signal.SignalMap {
+		signalNames = append(signalNames, k)
+	}
+	return completion.FromList(signalNames...)(cmd, args, toComplete)
+}

cli/command/container/completion_test.go

@@ -0,0 +1,135 @@
+package container
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/docker/cli/internal/test"
+	"github.com/docker/cli/internal/test/builders"
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/container"
+	"github.com/moby/sys/signal"
+	"github.com/spf13/cobra"
+	"gotest.tools/v3/assert"
+	is "gotest.tools/v3/assert/cmp"
+)
+
+func TestCompleteLinuxCapabilityNames(t *testing.T) {
+	names, directives := completeLinuxCapabilityNames(nil, nil, "")
+	assert.Check(t, is.Equal(directives&cobra.ShellCompDirectiveNoFileComp, cobra.ShellCompDirectiveNoFileComp), "Should not perform file completion")
+	assert.Assert(t, len(names) > 1)
+	assert.Check(t, names[0] == allCaps)
+	for _, name := range names[1:] {
+		assert.Check(t, strings.HasPrefix(name, "CAP_"))
+		assert.Check(t, is.Equal(name, strings.ToUpper(name)), "Should be formatted uppercase")
+	}
+}
+
+func TestCompletePid(t *testing.T) {
+	tests := []struct {
+		containerListFunc   func(container.ListOptions) ([]types.Container, error)
+		toComplete          string
+		expectedCompletions []string
+		expectedDirective   cobra.ShellCompDirective
+	}{
+		{
+			toComplete:          "",
+			expectedCompletions: []string{"container:", "host"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete:          "c",
+			expectedCompletions: []string{"container:"},
+			expectedDirective:   cobra.ShellCompDirectiveNoSpace,
+		},
+		{
+			containerListFunc: func(container.ListOptions) ([]types.Container, error) {
+				return []types.Container{
+					*builders.Container("c1"),
+					*builders.Container("c2"),
+				}, nil
+			},
+			toComplete:          "container:",
+			expectedCompletions: []string{"container:c1", "container:c2"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.toComplete, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{
+				containerListFunc: tc.containerListFunc,
+			})
+			completions, directive := completePid(cli)(NewRunCommand(cli), nil, tc.toComplete)
+			assert.Check(t, is.DeepEqual(completions, tc.expectedCompletions))
+			assert.Check(t, is.Equal(directive, tc.expectedDirective))
+		})
+	}
+}
+
+func TestCompleteRestartPolicies(t *testing.T) {
+	values, directives := completeRestartPolicies(nil, nil, "")
+	assert.Check(t, is.Equal(directives&cobra.ShellCompDirectiveNoFileComp, cobra.ShellCompDirectiveNoFileComp), "Should not perform file completion")
+	expected := restartPolicies
+	assert.Check(t, is.DeepEqual(values, expected))
+}
+
+func TestCompleteSecurityOpt(t *testing.T) {
+	tests := []struct {
+		toComplete          string
+		expectedCompletions []string
+		expectedDirective   cobra.ShellCompDirective
+	}{
+		{
+			toComplete:          "",
+			expectedCompletions: []string{"apparmor=", "label=", "no-new-privileges", "seccomp=", "systempaths=unconfined"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete:          "apparmor=",
+			expectedCompletions: []string{"apparmor="},
+			expectedDirective:   cobra.ShellCompDirectiveNoSpace,
+		},
+		{
+			toComplete:          "label=",
+			expectedCompletions: []string{"label=disable", "label=level:", "label=role:", "label=type:", "label=user:"},
+			expectedDirective:   cobra.ShellCompDirectiveNoSpace | cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete: "s",
+			// We do not filter matching completions but delegate this task to the shell script.
+			expectedCompletions: []string{"apparmor=", "label=", "no-new-privileges", "seccomp=", "systempaths=unconfined"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete:          "se",
+			expectedCompletions: []string{"seccomp="},
+			expectedDirective:   cobra.ShellCompDirectiveNoSpace,
+		},
+		{
+			toComplete:          "seccomp=",
+			expectedCompletions: []string{"seccomp=unconfined"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+		{
+			toComplete:          "sy",
+			expectedCompletions: []string{"apparmor=", "label=", "no-new-privileges", "seccomp=", "systempaths=unconfined"},
+			expectedDirective:   cobra.ShellCompDirectiveNoFileComp,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.toComplete, func(t *testing.T) {
+			completions, directive := completeSecurityOpt(nil, nil, tc.toComplete)
+			assert.Check(t, is.DeepEqual(completions, tc.expectedCompletions))
+			assert.Check(t, is.Equal(directive, tc.expectedDirective))
+		})
+	}
+}
+
+func TestCompleteSignals(t *testing.T) {
+	values, directives := completeSignals(nil, nil, "")
+	assert.Check(t, is.Equal(directives&cobra.ShellCompDirectiveNoFileComp, cobra.ShellCompDirectiveNoFileComp), "Should not perform file completion")
+	assert.Check(t, len(values) > 1)
+	assert.Check(t, is.Len(values, len(signal.SignalMap)))
+}

cli/command/container/cp.go

@@ -17,7 +17,6 @@ import (
 	"github.com/docker/cli/cli/streams"
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/pkg/archive"
-	"github.com/docker/docker/pkg/system"
 	units "github.com/docker/go-units"
 	"github.com/morikuni/aec"
 	"github.com/pkg/errors"
@@ -235,7 +234,7 @@ func copyFromContainer(ctx context.Context, dockerCli command.Cli, copyConfig cp
 		// If the destination is a symbolic link, we should follow it.
 		if err == nil && srcStat.Mode&os.ModeSymlink != 0 {
 			linkTarget := srcStat.LinkTarget
-			if !system.IsAbs(linkTarget) {
+			if !isAbs(linkTarget) {
 				// Join with the parent directory.
 				srcParent, _ := archive.SplitPathDirEntry(srcPath)
 				linkTarget = filepath.Join(srcParent, linkTarget)
@@ -319,7 +318,7 @@ func copyToContainer(ctx context.Context, dockerCli command.Cli, copyConfig cpCo
 	// If the destination is a symbolic link, we should evaluate it.
 	if err == nil && dstStat.Mode&os.ModeSymlink != 0 {
 		linkTarget := dstStat.LinkTarget
-		if !system.IsAbs(linkTarget) {
+		if !isAbs(linkTarget) {
 			// Join with the parent directory.
 			dstParent, _ := archive.SplitPathDirEntry(dstPath)
 			linkTarget = filepath.Join(dstParent, linkTarget)
@@ -434,7 +433,7 @@ func copyToContainer(ctx context.Context, dockerCli command.Cli, copyConfig cpCo
 // client, a `:` could be part of an absolute Windows path, in which case it
 // is immediately proceeded by a backslash.
 func splitCpArg(arg string) (ctr, path string) {
-	if system.IsAbs(arg) {
+	if isAbs(arg) {
 		// Explicit local absolute path, e.g., `C:\foo` or `/foo`.
 		return "", arg
 	}
@@ -448,3 +447,15 @@ func splitCpArg(arg string) (ctr, path string) {
 
 	return ctr, path
 }
+
+// IsAbs is a platform-agnostic wrapper for filepath.IsAbs.
+//
+// On Windows, golang filepath.IsAbs does not consider a path \windows\system32
+// as absolute as it doesn't start with a drive-letter/colon combination. However,
+// in docker we need to verify things such as WORKDIR /windows/system32 in
+// a Dockerfile (which gets translated to \windows\system32 when being processed
+// by the daemon). This SHOULD be treated as absolute from a docker processing
+// perspective.
+func isAbs(path string) bool {
+	return filepath.IsAbs(path) || strings.HasPrefix(path, string(os.PathSeparator))
+}

cli/command/container/cp_test.go

@@ -67,14 +67,15 @@ func TestRunCopyFromContainerToStdout(t *testing.T) {
 }
 
 func TestRunCopyFromContainerToFilesystem(t *testing.T) {
-	destDir := fs.NewDir(t, "cp-test",
+	srcDir := fs.NewDir(t, "cp-test",
 		fs.WithFile("file1", "content\n"))
-	defer destDir.Remove()
+
+	destDir := fs.NewDir(t, "cp-test")
 
 	cli := test.NewFakeCli(&fakeClient{
 		containerCopyFromFunc: func(ctr, srcPath string) (io.ReadCloser, container.PathStat, error) {
 			assert.Check(t, is.Equal("container", ctr))
-			readCloser, err := archive.TarWithOptions(destDir.Path(), &archive.TarOptions{})
+			readCloser, err := archive.Tar(srcDir.Path(), archive.Uncompressed)
 			return readCloser, container.PathStat{}, err
 		},
 	})
@@ -178,13 +179,14 @@ func TestSplitCpArg(t *testing.T) {
 			expectedContainer: "container",
 		},
 	}
-	for _, testcase := range testcases {
-		t.Run(testcase.doc, func(t *testing.T) {
-			skip.If(t, testcase.os != "" && testcase.os != runtime.GOOS)
+	for _, tc := range testcases {
+		tc := tc
+		t.Run(tc.doc, func(t *testing.T) {
+			skip.If(t, tc.os == "windows" && runtime.GOOS != "windows" || tc.os == "linux" && runtime.GOOS == "windows")
 
-			ctr, path := splitCpArg(testcase.path)
-			assert.Check(t, is.Equal(testcase.expectedContainer, ctr))
-			assert.Check(t, is.Equal(testcase.expectedPath, path))
+			ctr, path := splitCpArg(tc.path)
+			assert.Check(t, is.Equal(tc.expectedContainer, ctr))
+			assert.Check(t, is.Equal(tc.expectedPath, path))
 		})
 	}
 }

cli/command/container/create.go

@@ -77,6 +77,16 @@ func NewCreateCommand(dockerCli command.Cli) *cobra.Command {
 	command.AddPlatformFlag(flags, &options.platform)
 	command.AddTrustVerificationFlags(flags, &options.untrusted, dockerCli.ContentTrustEnabled())
 	copts = addFlags(flags)
+
+	addCompletions(cmd, dockerCli)
+
+	flags.VisitAll(func(flag *pflag.Flag) {
+		// Set a default completion function if none was set. We don't look
+		// up if it does already have one set, because Cobra does this for
+		// us, and returns an error (which we ignore for this reason).
+		_ = cmd.RegisterFlagCompletionFunc(flag.Name, completion.NoComplete)
+	})
+
 	return cmd
 }
 

cli/command/container/create_test.go

@@ -133,7 +133,7 @@ func TestCreateContainerImagePullPolicy(t *testing.T) {
 						return container.CreateResponse{ID: containerID}, nil
 					}
 				},
-				imageCreateFunc: func(parentReference string, options image.CreateOptions) (io.ReadCloser, error) {
+				imageCreateFunc: func(ctx context.Context, parentReference string, options image.CreateOptions) (io.ReadCloser, error) {
 					defer func() { pullCounter++ }()
 					return io.NopCloser(strings.NewReader("")), nil
 				},
@@ -236,6 +236,7 @@ func TestNewCreateCommandWithContentTrustErrors(t *testing.T) {
 		fakeCLI.SetNotaryClient(tc.notaryFunc)
 		cmd := NewCreateCommand(fakeCLI)
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		cmd.SetArgs(tc.args)
 		err := cmd.Execute()
 		assert.ErrorContains(t, err, tc.expectedError)

cli/command/container/exec.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"io"
-	"os"
 
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
@@ -79,12 +78,8 @@ func NewExecCommand(dockerCli command.Cli) *cobra.Command {
 	flags.StringVarP(&options.Workdir, "workdir", "w", "", "Working directory inside the container")
 	flags.SetAnnotation("workdir", "version", []string{"1.35"})
 
-	_ = cmd.RegisterFlagCompletionFunc("env", func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
-		return os.Environ(), cobra.ShellCompDirectiveNoFileComp
-	})
-	_ = cmd.RegisterFlagCompletionFunc("env-file", func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
-		return nil, cobra.ShellCompDirectiveDefault // _filedir
-	})
+	_ = cmd.RegisterFlagCompletionFunc("env", completion.EnvVarNames)
+	_ = cmd.RegisterFlagCompletionFunc("env-file", completion.FileNames)
 
 	return cmd
 }

cli/command/container/export_test.go

@@ -39,6 +39,7 @@ func TestContainerExportOutputToIrregularFile(t *testing.T) {
 	})
 	cmd := NewExportCommand(cli)
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	cmd.SetArgs([]string{"-o", "/dev/random", "container"})
 
 	err := cmd.Execute()

cli/command/container/inspect.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package container
 

cli/command/container/kill.go

@@ -38,6 +38,9 @@ func NewKillCommand(dockerCli command.Cli) *cobra.Command {
 
 	flags := cmd.Flags()
 	flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
+
+	_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)
+
 	return cmd
 }
 
@@ -50,7 +53,7 @@ func runKill(ctx context.Context, dockerCli command.Cli, opts *killOptions) erro
 		if err := <-errChan; err != nil {
 			errs = append(errs, err.Error())
 		} else {
-			fmt.Fprintln(dockerCli.Out(), name)
+			_, _ = fmt.Fprintln(dockerCli.Out(), name)
 		}
 	}
 	if len(errs) > 0 {

cli/command/container/list_test.go

@@ -128,7 +128,6 @@ func TestContainerListBuildContainerListOptions(t *testing.T) {
 
 func TestContainerListErrors(t *testing.T) {
 	testCases := []struct {
-		args              []string
 		flags             map[string]string
 		containerListFunc func(container.ListOptions) ([]types.Container, error)
 		expectedError     string
@@ -158,11 +157,12 @@ func TestContainerListErrors(t *testing.T) {
 				containerListFunc: tc.containerListFunc,
 			}),
 		)
-		cmd.SetArgs(tc.args)
 		for key, value := range tc.flags {
 			assert.Check(t, cmd.Flags().Set(key, value))
 		}
+		cmd.SetArgs([]string{})
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
 }
@@ -180,6 +180,9 @@ func TestContainerListWithoutFormat(t *testing.T) {
 		},
 	})
 	cmd := newListCommand(cli)
+	cmd.SetArgs([]string{})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	assert.NilError(t, cmd.Execute())
 	golden.Assert(t, cli.OutBuffer().String(), "container-list-without-format.golden")
 }
@@ -194,6 +197,9 @@ func TestContainerListNoTrunc(t *testing.T) {
 		},
 	})
 	cmd := newListCommand(cli)
+	cmd.SetArgs([]string{})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	assert.Check(t, cmd.Flags().Set("no-trunc", "true"))
 	assert.NilError(t, cmd.Execute())
 	golden.Assert(t, cli.OutBuffer().String(), "container-list-without-format-no-trunc.golden")
@@ -210,6 +216,9 @@ func TestContainerListNamesMultipleTime(t *testing.T) {
 		},
 	})
 	cmd := newListCommand(cli)
+	cmd.SetArgs([]string{})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	assert.Check(t, cmd.Flags().Set("format", "{{.Names}} {{.Names}}"))
 	assert.NilError(t, cmd.Execute())
 	golden.Assert(t, cli.OutBuffer().String(), "container-list-format-name-name.golden")
@@ -226,6 +235,9 @@ func TestContainerListFormatTemplateWithArg(t *testing.T) {
 		},
 	})
 	cmd := newListCommand(cli)
+	cmd.SetArgs([]string{})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	assert.Check(t, cmd.Flags().Set("format", `{{.Names}} {{.Label "some.label"}}`))
 	assert.NilError(t, cmd.Execute())
 	golden.Assert(t, cli.OutBuffer().String(), "container-list-format-with-arg.golden")
@@ -275,6 +287,9 @@ func TestContainerListFormatSizeSetsOption(t *testing.T) {
 				},
 			})
 			cmd := newListCommand(cli)
+			cmd.SetArgs([]string{})
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
 			assert.Check(t, cmd.Flags().Set("format", tc.format))
 			if tc.sizeFlag != "" {
 				assert.Check(t, cmd.Flags().Set("size", tc.sizeFlag))
@@ -297,6 +312,9 @@ func TestContainerListWithConfigFormat(t *testing.T) {
 		PsFormat: "{{ .Names }} {{ .Image }} {{ .Labels }} {{ .Size}}",
 	})
 	cmd := newListCommand(cli)
+	cmd.SetArgs([]string{})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	assert.NilError(t, cmd.Execute())
 	golden.Assert(t, cli.OutBuffer().String(), "container-list-with-config-format.golden")
 }
@@ -314,6 +332,9 @@ func TestContainerListWithFormat(t *testing.T) {
 	t.Run("with format", func(t *testing.T) {
 		cli.OutBuffer().Reset()
 		cmd := newListCommand(cli)
+		cmd.SetArgs([]string{})
+		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.Check(t, cmd.Flags().Set("format", "{{ .Names }} {{ .Image }} {{ .Labels }}"))
 		assert.NilError(t, cmd.Execute())
 		golden.Assert(t, cli.OutBuffer().String(), "container-list-with-format.golden")
@@ -322,6 +343,9 @@ func TestContainerListWithFormat(t *testing.T) {
 	t.Run("with format and quiet", func(t *testing.T) {
 		cli.OutBuffer().Reset()
 		cmd := newListCommand(cli)
+		cmd.SetArgs([]string{})
+		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.Check(t, cmd.Flags().Set("format", "{{ .Names }} {{ .Image }} {{ .Labels }}"))
 		assert.Check(t, cmd.Flags().Set("quiet", "true"))
 		assert.NilError(t, cmd.Execute())

cli/command/container/opts_test.go

@@ -921,7 +921,7 @@ func TestParseEnvfileVariablesWithBOMUnicode(t *testing.T) {
 	}
 
 	// UTF16 with BOM
-	e := "contains invalid utf8 bytes at line"
+	e := "invalid utf8 bytes at line"
 	if _, _, _, err := parseRun([]string{"--env-file=testdata/utf16.env", "img", "cmd"}); err == nil || !strings.Contains(err.Error(), e) {
 		t.Fatalf("Expected an error with message '%s', got %v", e, err)
 	}

cli/command/container/prune_test.go

@@ -2,6 +2,7 @@ package container
 
 import (
 	"context"
+	"io"
 	"testing"
 
 	"github.com/docker/cli/internal/test"
@@ -20,5 +21,8 @@ func TestContainerPrunePromptTermination(t *testing.T) {
 		},
 	})
 	cmd := NewPruneCommand(cli)
+	cmd.SetArgs([]string{})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	test.TerminatePrompt(ctx, t, cmd, cli)
 }

cli/command/container/restart.go

@@ -43,6 +43,9 @@ func NewRestartCommand(dockerCli command.Cli) *cobra.Command {
 	flags := cmd.Flags()
 	flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
 	flags.IntVarP(&opts.timeout, "time", "t", 0, "Seconds to wait before killing the container")
+
+	_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)
+
 	return cmd
 }
 

cli/command/container/rm.go

@@ -8,6 +8,7 @@ import (
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/cli/cli/command/completion"
+	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/container"
 	"github.com/docker/docker/errdefs"
 	"github.com/pkg/errors"
@@ -38,7 +39,9 @@ func NewRmCommand(dockerCli command.Cli) *cobra.Command {
 		Annotations: map[string]string{
 			"aliases": "docker container rm, docker container remove, docker rm",
 		},
-		ValidArgsFunction: completion.ContainerNames(dockerCli, true),
+		ValidArgsFunction: completion.ContainerNames(dockerCli, true, func(ctr types.Container) bool {
+			return opts.force || ctr.State == "exited" || ctr.State == "created"
+		}),
 	}
 
 	flags := cmd.Flags()

cli/command/container/rm_test.go

@@ -45,6 +45,7 @@ func TestRemoveForce(t *testing.T) {
 			})
 			cmd := NewRmCommand(cli)
 			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
 			cmd.SetArgs(tc.args)
 
 			err := cmd.Execute()

cli/command/container/run.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"io"
-	"os"
 	"strings"
 	"syscall"
 
@@ -70,22 +69,16 @@ func NewRunCommand(dockerCli command.Cli) *cobra.Command {
 	command.AddTrustVerificationFlags(flags, &options.untrusted, dockerCli.ContentTrustEnabled())
 	copts = addFlags(flags)
 
-	cmd.RegisterFlagCompletionFunc(
-		"env",
-		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-			return os.Environ(), cobra.ShellCompDirectiveNoFileComp
-		},
-	)
-	cmd.RegisterFlagCompletionFunc(
-		"env-file",
-		func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-			return nil, cobra.ShellCompDirectiveDefault
-		},
-	)
-	cmd.RegisterFlagCompletionFunc(
-		"network",
-		completion.NetworkNames(dockerCli),
-	)
+	_ = cmd.RegisterFlagCompletionFunc("detach-keys", completeDetachKeys)
+	addCompletions(cmd, dockerCli)
+
+	flags.VisitAll(func(flag *pflag.Flag) {
+		// Set a default completion function if none was set. We don't look
+		// up if it does already have one set, because Cobra does this for
+		// us, and returns an error (which we ignore for this reason).
+		_ = cmd.RegisterFlagCompletionFunc(flag.Name, completion.NoComplete)
+	})
+
 	return cmd
 }
 
@@ -140,9 +133,6 @@ func runContainer(ctx context.Context, dockerCli command.Cli, runOpts *runOption
 		config.StdinOnce = false
 	}
 
-	ctx, cancelFun := context.WithCancel(ctx)
-	defer cancelFun()
-
 	containerID, err := createContainer(ctx, dockerCli, containerCfg, &runOpts.createOptions)
 	if err != nil {
 		reportError(stderr, "run", err.Error(), true)
@@ -159,6 +149,9 @@ func runContainer(ctx context.Context, dockerCli command.Cli, runOpts *runOption
 		defer signal.StopCatch(sigc)
 	}
 
+	ctx, cancelFun := context.WithCancel(context.WithoutCancel(ctx))
+	defer cancelFun()
+
 	var (
 		waitDisplayID chan struct{}
 		errCh         chan error
@@ -178,6 +171,9 @@ func runContainer(ctx context.Context, dockerCli command.Cli, runOpts *runOption
 			detachKeys = runOpts.detachKeys
 		}
 
+		// ctx should not be cancellable here, as this would kill the stream to the container
+		// and we want to keep the stream open until the process in the container exits or until
+		// the user forcefully terminates the CLI.
 		closeFn, err := attachContainer(ctx, dockerCli, containerID, &errCh, config, container.AttachOptions{
 			Stream:     true,
 			Stdin:      config.AttachStdin,

cli/command/container/run_test.go

@@ -2,10 +2,11 @@ package container
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"io"
 	"net"
-	"os/signal"
 	"syscall"
 	"testing"
 	"time"
@@ -17,7 +18,9 @@ import (
 	"github.com/docker/cli/internal/test/notary"
 	"github.com/docker/docker/api/types"
 	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/api/types/network"
+	"github.com/docker/docker/pkg/jsonmessage"
 	specs "github.com/opencontainers/image-spec/specs-go/v1"
 	"github.com/spf13/pflag"
 	"gotest.tools/v3/assert"
@@ -38,15 +41,85 @@ func TestRunLabel(t *testing.T) {
 	assert.NilError(t, cmd.Execute())
 }
 
-func TestRunAttachTermination(t *testing.T) {
+func TestRunAttach(t *testing.T) {
 	p, tty, err := pty.Open()
 	assert.NilError(t, err)
-
 	defer func() {
 		_ = tty.Close()
 		_ = p.Close()
 	}()
 
+	var conn net.Conn
+	attachCh := make(chan struct{})
+	fakeCLI := test.NewFakeCli(&fakeClient{
+		createContainerFunc: func(_ *container.Config, _ *container.HostConfig, _ *network.NetworkingConfig, _ *specs.Platform, _ string) (container.CreateResponse, error) {
+			return container.CreateResponse{
+				ID: "id",
+			}, nil
+		},
+		containerAttachFunc: func(ctx context.Context, containerID string, options container.AttachOptions) (types.HijackedResponse, error) {
+			server, client := net.Pipe()
+			conn = server
+			t.Cleanup(func() {
+				_ = server.Close()
+			})
+			attachCh <- struct{}{}
+			return types.NewHijackedResponse(client, types.MediaTypeRawStream), nil
+		},
+		waitFunc: func(_ string) (<-chan container.WaitResponse, <-chan error) {
+			responseChan := make(chan container.WaitResponse, 1)
+			errChan := make(chan error)
+
+			responseChan <- container.WaitResponse{
+				StatusCode: 33,
+			}
+			return responseChan, errChan
+		},
+		// use new (non-legacy) wait API
+		// see: 38591f20d07795aaef45d400df89ca12f29c603b
+		Version: "1.30",
+	}, func(fc *test.FakeCli) {
+		fc.SetOut(streams.NewOut(tty))
+		fc.SetIn(streams.NewIn(tty))
+	})
+
+	cmd := NewRunCommand(fakeCLI)
+	cmd.SetArgs([]string{"-it", "busybox"})
+	cmd.SilenceUsage = true
+	cmdErrC := make(chan error, 1)
+	go func() {
+		cmdErrC <- cmd.Execute()
+	}()
+
+	// run command should attempt to attach to the container
+	select {
+	case <-time.After(5 * time.Second):
+		t.Fatal("containerAttachFunc was not called before the 5 second timeout")
+	case <-attachCh:
+	}
+
+	// end stream from "container" so that we'll detach
+	conn.Close()
+
+	select {
+	case cmdErr := <-cmdErrC:
+		assert.Equal(t, cmdErr, cli.StatusError{
+			StatusCode: 33,
+		})
+	case <-time.After(2 * time.Second):
+		t.Fatal("cmd did not return within timeout")
+	}
+}
+
+func TestRunAttachTermination(t *testing.T) {
+	p, tty, err := pty.Open()
+	assert.NilError(t, err)
+	defer func() {
+		_ = tty.Close()
+		_ = p.Close()
+	}()
+
+	var conn net.Conn
 	killCh := make(chan struct{})
 	attachCh := make(chan struct{})
 	fakeCLI := test.NewFakeCli(&fakeClient{
@@ -61,42 +134,143 @@ func TestRunAttachTermination(t *testing.T) {
 		},
 		containerAttachFunc: func(ctx context.Context, containerID string, options container.AttachOptions) (types.HijackedResponse, error) {
 			server, client := net.Pipe()
+			conn = server
 			t.Cleanup(func() {
 				_ = server.Close()
 			})
 			attachCh <- struct{}{}
 			return types.NewHijackedResponse(client, types.MediaTypeRawStream), nil
 		},
-		Version: "1.36",
+		waitFunc: func(_ string) (<-chan container.WaitResponse, <-chan error) {
+			responseChan := make(chan container.WaitResponse, 1)
+			errChan := make(chan error)
+
+			responseChan <- container.WaitResponse{
+				StatusCode: 130,
+			}
+			return responseChan, errChan
+		},
+		// use new (non-legacy) wait API
+		// see: 38591f20d07795aaef45d400df89ca12f29c603b
+		Version: "1.30",
 	}, func(fc *test.FakeCli) {
 		fc.SetOut(streams.NewOut(tty))
 		fc.SetIn(streams.NewIn(tty))
 	})
-	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGTERM)
-	defer cancel()
-
-	assert.Equal(t, fakeCLI.In().IsTerminal(), true)
-	assert.Equal(t, fakeCLI.Out().IsTerminal(), true)
 
 	cmd := NewRunCommand(fakeCLI)
 	cmd.SetArgs([]string{"-it", "busybox"})
 	cmd.SilenceUsage = true
+	cmdErrC := make(chan error, 1)
 	go func() {
-		assert.ErrorIs(t, cmd.ExecuteContext(ctx), context.Canceled)
+		cmdErrC <- cmd.Execute()
+	}()
+
+	// run command should attempt to attach to the container
+	select {
+	case <-time.After(5 * time.Second):
+		t.Fatal("containerAttachFunc was not called before the timeout")
+	case <-attachCh:
+	}
+
+	assert.NilError(t, syscall.Kill(syscall.Getpid(), syscall.SIGINT))
+	// end stream from "container" so that we'll detach
+	conn.Close()
+
+	select {
+	case <-killCh:
+	case <-time.After(5 * time.Second):
+		t.Fatal("containerKillFunc was not called before the timeout")
+	}
+
+	select {
+	case cmdErr := <-cmdErrC:
+		assert.Equal(t, cmdErr, cli.StatusError{
+			StatusCode: 130,
+		})
+	case <-time.After(2 * time.Second):
+		t.Fatal("cmd did not return before the timeout")
+	}
+}
+
+func TestRunPullTermination(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+
+	attachCh := make(chan struct{})
+	fakeCLI := test.NewFakeCli(&fakeClient{
+		createContainerFunc: func(config *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig,
+			platform *specs.Platform, containerName string,
+		) (container.CreateResponse, error) {
+			select {
+			case <-ctx.Done():
+				return container.CreateResponse{}, ctx.Err()
+			default:
+			}
+			return container.CreateResponse{}, fakeNotFound{}
+		},
+		containerAttachFunc: func(ctx context.Context, containerID string, options container.AttachOptions) (types.HijackedResponse, error) {
+			return types.HijackedResponse{}, errors.New("shouldn't try to attach to a container")
+		},
+		imageCreateFunc: func(ctx context.Context, parentReference string, options image.CreateOptions) (io.ReadCloser, error) {
+			server, client := net.Pipe()
+			t.Cleanup(func() {
+				_ = server.Close()
+			})
+			go func() {
+				enc := json.NewEncoder(server)
+				for i := 0; i < 100; i++ {
+					select {
+					case <-ctx.Done():
+						assert.NilError(t, server.Close(), "failed to close imageCreateFunc server")
+						return
+					default:
+					}
+					assert.NilError(t, enc.Encode(jsonmessage.JSONMessage{
+						Status:   "Downloading",
+						ID:       fmt.Sprintf("id-%d", i),
+						TimeNano: time.Now().UnixNano(),
+						Time:     time.Now().Unix(),
+						Progress: &jsonmessage.JSONProgress{
+							Current: int64(i),
+							Total:   100,
+							Start:   0,
+						},
+					}))
+					time.Sleep(100 * time.Millisecond)
+				}
+			}()
+			attachCh <- struct{}{}
+			return client, nil
+		},
+		Version: "1.30",
+	})
+
+	cmd := NewRunCommand(fakeCLI)
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs([]string{"foobar:latest"})
+
+	cmdErrC := make(chan error, 1)
+	go func() {
+		cmdErrC <- cmd.ExecuteContext(ctx)
 	}()
 
 	select {
 	case <-time.After(5 * time.Second):
-		t.Fatal("containerAttachFunc was not called before the 5 second timeout")
+		t.Fatal("imageCreateFunc was not called before the timeout")
 	case <-attachCh:
 	}
 
-	assert.NilError(t, syscall.Kill(syscall.Getpid(), syscall.SIGTERM))
+	cancel()
+
 	select {
-	case <-time.After(5 * time.Second):
-		cancel()
-		t.Fatal("containerKillFunc was not called before the 5 second timeout")
-	case <-killCh:
+	case cmdErr := <-cmdErrC:
+		assert.Equal(t, cmdErr, cli.StatusError{
+			StatusCode: 125,
+		})
+	case <-time.After(10 * time.Second):
+		t.Fatal("cmd did not return before the timeout")
 	}
 }
 
@@ -127,23 +301,27 @@ func TestRunCommandWithContentTrustErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		fakeCLI := test.NewFakeCli(&fakeClient{
-			createContainerFunc: func(config *container.Config,
-				hostConfig *container.HostConfig,
-				networkingConfig *network.NetworkingConfig,
-				platform *specs.Platform,
-				containerName string,
-			) (container.CreateResponse, error) {
-				return container.CreateResponse{}, errors.New("shouldn't try to pull image")
-			},
-		}, test.EnableContentTrust)
-		fakeCLI.SetNotaryClient(tc.notaryFunc)
-		cmd := NewRunCommand(fakeCLI)
-		cmd.SetArgs(tc.args)
-		cmd.SetOut(io.Discard)
-		err := cmd.Execute()
-		assert.Assert(t, err != nil)
-		assert.Assert(t, is.Contains(fakeCLI.ErrBuffer().String(), tc.expectedError))
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			fakeCLI := test.NewFakeCli(&fakeClient{
+				createContainerFunc: func(config *container.Config,
+					hostConfig *container.HostConfig,
+					networkingConfig *network.NetworkingConfig,
+					platform *specs.Platform,
+					containerName string,
+				) (container.CreateResponse, error) {
+					return container.CreateResponse{}, errors.New("shouldn't try to pull image")
+				},
+			}, test.EnableContentTrust)
+			fakeCLI.SetNotaryClient(tc.notaryFunc)
+			cmd := NewRunCommand(fakeCLI)
+			cmd.SetArgs(tc.args)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			err := cmd.Execute()
+			assert.Assert(t, err != nil)
+			assert.Assert(t, is.Contains(fakeCLI.ErrBuffer().String(), tc.expectedError))
+		})
 	}
 }
 

cli/command/container/stats.go

@@ -1,6 +1,7 @@
 package container
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"io"
@@ -264,31 +265,50 @@ func RunStats(ctx context.Context, dockerCLI command.Cli, options *StatsOptions)
 		// so we unlikely hit this code in practice.
 		daemonOSType = dockerCLI.ServerInfo().OSType
 	}
+
+	// Buffer to store formatted stats text.
+	// Once formatted, it will be printed in one write to avoid screen flickering.
+	var statsTextBuffer bytes.Buffer
+
 	statsCtx := formatter.Context{
-		Output: dockerCLI.Out(),
+		Output: &statsTextBuffer,
 		Format: NewStatsFormat(format, daemonOSType),
 	}
-	cleanScreen := func() {
-		if !options.NoStream {
-			_, _ = fmt.Fprint(dockerCLI.Out(), "\033[2J")
-			_, _ = fmt.Fprint(dockerCLI.Out(), "\033[H")
-		}
-	}
 
 	var err error
 	ticker := time.NewTicker(500 * time.Millisecond)
 	defer ticker.Stop()
 	for range ticker.C {
-		cleanScreen()
 		var ccStats []StatsEntry
 		cStats.mu.RLock()
 		for _, c := range cStats.cs {
 			ccStats = append(ccStats, c.GetStatistics())
 		}
 		cStats.mu.RUnlock()
+
+		if !options.NoStream {
+			// Start by moving the cursor to the top-left
+			_, _ = fmt.Fprint(&statsTextBuffer, "\033[H")
+		}
+
 		if err = statsFormatWrite(statsCtx, ccStats, daemonOSType, !options.NoTrunc); err != nil {
 			break
 		}
+
+		if !options.NoStream {
+			for _, line := range strings.Split(statsTextBuffer.String(), "\n") {
+				// In case the new text is shorter than the one we are writing over,
+				// we'll append the "erase line" escape sequence to clear the remaining text.
+				_, _ = fmt.Fprint(&statsTextBuffer, line, "\033[K\n")
+			}
+
+			// We might have fewer containers than before, so let's clear the remaining text
+			_, _ = fmt.Fprint(&statsTextBuffer, "\033[J")
+		}
+
+		_, _ = fmt.Fprint(dockerCLI.Out(), statsTextBuffer.String())
+		statsTextBuffer.Reset()
+
 		if len(cStats.cs) == 0 && !showAll {
 			break
 		}

cli/command/container/stop.go

@@ -43,6 +43,9 @@ func NewStopCommand(dockerCli command.Cli) *cobra.Command {
 	flags := cmd.Flags()
 	flags.StringVarP(&opts.signal, "signal", "s", "", "Signal to send to the container")
 	flags.IntVarP(&opts.timeout, "time", "t", 0, "Seconds to wait before killing the container")
+
+	_ = cmd.RegisterFlagCompletionFunc("signal", completeSignals)
+
 	return cmd
 }
 

cli/command/container/update.go

@@ -83,6 +83,8 @@ func NewUpdateCommand(dockerCli command.Cli) *cobra.Command {
 	flags.Var(&options.cpus, "cpus", "Number of CPUs")
 	flags.SetAnnotation("cpus", "version", []string{"1.29"})
 
+	_ = cmd.RegisterFlagCompletionFunc("restart", completeRestartPolicies)
+
 	return cmd
 }
 

cli/command/container/utils_test.go

@@ -38,7 +38,7 @@ func waitFn(cid string) (<-chan container.WaitResponse, <-chan error) {
 }
 
 func TestWaitExitOrRemoved(t *testing.T) {
-	testcases := []struct {
+	tests := []struct {
 		cid      string
 		exitCode int
 	}{
@@ -61,9 +61,11 @@ func TestWaitExitOrRemoved(t *testing.T) {
 	}
 
 	client := &fakeClient{waitFunc: waitFn, Version: api.DefaultVersion}
-	for _, testcase := range testcases {
-		statusC := waitExitOrRemoved(context.Background(), client, testcase.cid, true)
-		exitCode := <-statusC
-		assert.Check(t, is.Equal(testcase.exitCode, exitCode))
+	for _, tc := range tests {
+		t.Run(tc.cid, func(t *testing.T) {
+			statusC := waitExitOrRemoved(context.Background(), client, tc.cid, true)
+			exitCode := <-statusC
+			assert.Check(t, is.Equal(tc.exitCode, exitCode))
+		})
 	}
 }

cli/command/context.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package command
 

cli/command/context/create.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package context
 

cli/command/context/create_test.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package context
 

cli/command/context/inspect.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package context
 

cli/command/context/list.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package context
 

cli/command/context_test.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package command
 

cli/command/defaultcontextstore.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package command
 

cli/command/defaultcontextstore_test.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package command
 

cli/command/formatter/container.go

@@ -1,10 +1,11 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package formatter
 
 import (
 	"fmt"
+	"net"
 	"sort"
 	"strconv"
 	"strings"
@@ -331,7 +332,8 @@ func DisplayablePorts(ports []types.Port) string {
 		portKey := port.Type
 		if port.IP != "" {
 			if port.PublicPort != current {
-				hostMappings = append(hostMappings, fmt.Sprintf("%s:%d->%d/%s", port.IP, port.PublicPort, port.PrivatePort, port.Type))
+				hAddrPort := net.JoinHostPort(port.IP, strconv.Itoa(int(port.PublicPort)))
+				hostMappings = append(hostMappings, fmt.Sprintf("%s->%d/%s", hAddrPort, port.PrivatePort, port.Type))
 				continue
 			}
 			portKey = port.IP + "/" + port.Type

cli/command/formatter/container_test.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package formatter
 
@@ -471,6 +471,16 @@ func TestDisplayablePorts(t *testing.T) {
 			},
 			"0.0.0.0:0->9988/tcp",
 		},
+		{
+			[]types.Port{
+				{
+					IP:          "::",
+					PrivatePort: 9988,
+					Type:        "tcp",
+				},
+			},
+			"[::]:0->9988/tcp",
+		},
 		{
 			[]types.Port{
 				{

cli/command/formatter/custom.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package formatter
 

cli/command/formatter/formatter.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package formatter
 

cli/command/formatter/formatter_test.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package formatter
 

cli/command/formatter/reflect.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package formatter
 

cli/command/formatter/reflect_test.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package formatter
 

cli/command/formatter/volume_test.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package formatter
 

cli/command/idresolver/idresolver.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package idresolver
 

cli/command/image/build.go

@@ -15,8 +15,10 @@ import (
 	"strings"
 
 	"github.com/distribution/reference"
+	"github.com/docker/cli-docs-tool/annotation"
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
+	"github.com/docker/cli/cli/command/completion"
 	"github.com/docker/cli/cli/command/image/build"
 	"github.com/docker/cli/opts"
 	"github.com/docker/docker/api"
@@ -104,7 +106,7 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
 		},
 		Annotations: map[string]string{
 			"category-top": "4",
-			"aliases":      "docker image build, docker build, docker buildx build, docker builder build",
+			"aliases":      "docker image build, docker build, docker builder build",
 		},
 		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 			return nil, cobra.ShellCompDirectiveFilterDirs
@@ -114,9 +116,12 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
 	flags := cmd.Flags()
 
 	flags.VarP(&options.tags, "tag", "t", `Name and optionally a tag in the "name:tag" format`)
+	flags.SetAnnotation("tag", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#tag"})
 	flags.Var(&options.buildArgs, "build-arg", "Set build-time variables")
+	flags.SetAnnotation("build-arg", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#build-arg"})
 	flags.Var(options.ulimits, "ulimit", "Ulimit options")
 	flags.StringVarP(&options.dockerfileName, "file", "f", "", `Name of the Dockerfile (Default is "PATH/Dockerfile")`)
+	flags.SetAnnotation("file", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#file"})
 	flags.VarP(&options.memory, "memory", "m", "Memory limit")
 	flags.Var(&options.memorySwap, "memory-swap", `Swap limit equal to memory plus swap: -1 to enable unlimited swap`)
 	flags.Var(&options.shmSize, "shm-size", `Size of "/dev/shm"`)
@@ -126,6 +131,7 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
 	flags.StringVar(&options.cpuSetCpus, "cpuset-cpus", "", "CPUs in which to allow execution (0-3, 0,1)")
 	flags.StringVar(&options.cpuSetMems, "cpuset-mems", "", "MEMs in which to allow execution (0-3, 0,1)")
 	flags.StringVar(&options.cgroupParent, "cgroup-parent", "", `Set the parent cgroup for the "RUN" instructions during build`)
+	flags.SetAnnotation("cgroup-parent", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#cgroup-parent"})
 	flags.StringVar(&options.isolation, "isolation", "", "Container isolation technology")
 	flags.Var(&options.labels, "label", "Set metadata for an image")
 	flags.BoolVar(&options.noCache, "no-cache", false, "Do not use cache when building the image")
@@ -138,8 +144,11 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
 	flags.StringSliceVar(&options.securityOpt, "security-opt", []string{}, "Security options")
 	flags.StringVar(&options.networkMode, "network", "default", "Set the networking mode for the RUN instructions during build")
 	flags.SetAnnotation("network", "version", []string{"1.25"})
+	flags.SetAnnotation("network", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#network"})
 	flags.Var(&options.extraHosts, "add-host", `Add a custom host-to-IP mapping ("host:ip")`)
+	flags.SetAnnotation("add-host", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#add-host"})
 	flags.StringVar(&options.target, "target", "", "Set the target build stage to build.")
+	flags.SetAnnotation("target", annotation.ExternalURL, []string{"https://docs.docker.com/reference/cli/docker/buildx/build/#target"})
 	flags.StringVar(&options.imageIDFile, "iidfile", "", "Write the image ID to the file")
 
 	command.AddTrustVerificationFlags(flags, &options.untrusted, dockerCli.ContentTrustEnabled())
@@ -151,6 +160,8 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
 	flags.SetAnnotation("squash", "experimental", nil)
 	flags.SetAnnotation("squash", "version", []string{"1.25"})
 
+	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
+
 	return cmd
 }
 

cli/command/image/build_test.go

@@ -127,6 +127,7 @@ func TestRunBuildFromGitHubSpecialCase(t *testing.T) {
 	// Clone a small repo that exists so git doesn't prompt for credentials
 	cmd.SetArgs([]string{"github.com/docker/for-win"})
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	err := cmd.Execute()
 	assert.ErrorContains(t, err, "unable to prepare context")
 	assert.ErrorContains(t, err, "docker-build-git")

cli/command/image/history.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
+	"github.com/docker/cli/cli/command/completion"
 	"github.com/docker/cli/cli/command/formatter"
 	flagsHelper "github.com/docker/cli/cli/flags"
 	"github.com/spf13/cobra"
@@ -31,6 +32,7 @@ func NewHistoryCommand(dockerCli command.Cli) *cobra.Command {
 			opts.image = args[0]
 			return runHistory(cmd.Context(), dockerCli, opts)
 		},
+		ValidArgsFunction: completion.ImageNames(dockerCli),
 		Annotations: map[string]string{
 			"aliases": "docker image history, docker history",
 		},

cli/command/image/history_test.go

@@ -35,10 +35,14 @@ func TestNewHistoryCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cmd := NewHistoryCommand(test.NewFakeCli(&fakeClient{imageHistoryFunc: tc.imageHistoryFunc}))
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := NewHistoryCommand(test.NewFakeCli(&fakeClient{imageHistoryFunc: tc.imageHistoryFunc}))
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 

cli/command/image/import.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
+	"github.com/docker/cli/cli/command/completion"
 	dockeropts "github.com/docker/cli/opts"
 	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/pkg/jsonmessage"
@@ -47,6 +48,7 @@ func NewImportCommand(dockerCli command.Cli) *cobra.Command {
 	flags.VarP(&options.changes, "change", "c", "Apply Dockerfile instruction to the created image")
 	flags.StringVarP(&options.message, "message", "m", "", "Set commit message for imported image")
 	command.AddPlatformFlag(flags, &options.platform)
+	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
 
 	return cmd
 }

cli/command/image/import_test.go

@@ -36,6 +36,7 @@ func TestNewImportCommandErrors(t *testing.T) {
 	for _, tc := range testCases {
 		cmd := NewImportCommand(test.NewFakeCli(&fakeClient{imageImportFunc: tc.imageImportFunc}))
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		cmd.SetArgs(tc.args)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
@@ -44,6 +45,7 @@ func TestNewImportCommandErrors(t *testing.T) {
 func TestNewImportCommandInvalidFile(t *testing.T) {
 	cmd := NewImportCommand(test.NewFakeCli(&fakeClient{}))
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	cmd.SetArgs([]string{"testdata/import-command-success.unexistent-file"})
 	assert.ErrorContains(t, cmd.Execute(), "testdata/import-command-success.unexistent-file")
 }
@@ -96,9 +98,13 @@ func TestNewImportCommandSuccess(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cmd := NewImportCommand(test.NewFakeCli(&fakeClient{imageImportFunc: tc.imageImportFunc}))
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.NilError(t, cmd.Execute())
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := NewImportCommand(test.NewFakeCli(&fakeClient{imageImportFunc: tc.imageImportFunc}))
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.NilError(t, cmd.Execute())
+		})
 	}
 }

cli/command/image/inspect.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package image
 
@@ -8,6 +8,7 @@ import (
 
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
+	"github.com/docker/cli/cli/command/completion"
 	"github.com/docker/cli/cli/command/inspect"
 	flagsHelper "github.com/docker/cli/cli/flags"
 	"github.com/spf13/cobra"
@@ -30,6 +31,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command {
 			opts.refs = args
 			return runInspect(cmd.Context(), dockerCli, opts)
 		},
+		ValidArgsFunction: completion.ImageNames(dockerCli),
 	}
 
 	flags := cmd.Flags()

cli/command/image/inspect_test.go

@@ -25,10 +25,14 @@ func TestNewInspectCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cmd := newInspectCommand(test.NewFakeCli(&fakeClient{}))
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := newInspectCommand(test.NewFakeCli(&fakeClient{}))
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 

cli/command/image/list.go

@@ -2,6 +2,7 @@ package image
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 
@@ -24,6 +25,7 @@ type imagesOptions struct {
 	format      string
 	filter      opts.FilterOpt
 	calledAs    string
+	tree        bool
 }
 
 // NewImagesCommand creates a new `docker images` command
@@ -59,6 +61,10 @@ func NewImagesCommand(dockerCLI command.Cli) *cobra.Command {
 	flags.StringVar(&options.format, "format", "", flagsHelper.FormatHelp)
 	flags.VarP(&options.filter, "filter", "f", "Filter output based on conditions provided")
 
+	flags.BoolVar(&options.tree, "tree", false, "List multi-platform images as a tree (EXPERIMENTAL)")
+	flags.SetAnnotation("tree", "version", []string{"1.47"})
+	flags.SetAnnotation("tree", "experimentalCLI", nil)
+
 	return cmd
 }
 
@@ -75,6 +81,26 @@ func runImages(ctx context.Context, dockerCLI command.Cli, options imagesOptions
 		filters.Add("reference", options.matchName)
 	}
 
+	if options.tree {
+		if options.quiet {
+			return errors.New("--quiet is not yet supported with --tree")
+		}
+		if options.noTrunc {
+			return errors.New("--no-trunc is not yet supported with --tree")
+		}
+		if options.showDigests {
+			return errors.New("--show-digest is not yet supported with --tree")
+		}
+		if options.format != "" {
+			return errors.New("--format is not yet supported with --tree")
+		}
+
+		return runTree(ctx, dockerCLI, treeOptions{
+			all:     options.all,
+			filters: filters,
+		})
+	}
+
 	images, err := dockerCLI.Client().ImageList(ctx, image.ListOptions{
 		All:     options.all,
 		Filters: filters,

cli/command/image/list_test.go

@@ -35,10 +35,14 @@ func TestNewImagesCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cmd := NewImagesCommand(test.NewFakeCli(&fakeClient{imageListFunc: tc.imageListFunc}))
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := NewImagesCommand(test.NewFakeCli(&fakeClient{imageListFunc: tc.imageListFunc}))
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 
@@ -79,14 +83,18 @@ func TestNewImagesCommandSuccess(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(&fakeClient{imageListFunc: tc.imageListFunc})
-		cli.SetConfigFile(&configfile.ConfigFile{ImagesFormat: tc.imageFormat})
-		cmd := NewImagesCommand(cli)
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		err := cmd.Execute()
-		assert.NilError(t, err)
-		golden.Assert(t, cli.OutBuffer().String(), fmt.Sprintf("list-command-success.%s.golden", tc.name))
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{imageListFunc: tc.imageListFunc})
+			cli.SetConfigFile(&configfile.ConfigFile{ImagesFormat: tc.imageFormat})
+			cmd := NewImagesCommand(cli)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			err := cmd.Execute()
+			assert.NilError(t, err)
+			golden.Assert(t, cli.OutBuffer().String(), fmt.Sprintf("list-command-success.%s.golden", tc.name))
+		})
 	}
 }
 

cli/command/image/load_test.go

@@ -40,12 +40,16 @@ func TestNewLoadCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(&fakeClient{imageLoadFunc: tc.imageLoadFunc})
-		cli.In().SetIsTerminal(tc.isTerminalIn)
-		cmd := NewLoadCommand(cli)
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{imageLoadFunc: tc.imageLoadFunc})
+			cli.In().SetIsTerminal(tc.isTerminalIn)
+			cmd := NewLoadCommand(cli)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 
@@ -53,6 +57,7 @@ func TestNewLoadCommandInvalidInput(t *testing.T) {
 	expectedError := "open *"
 	cmd := NewLoadCommand(test.NewFakeCli(&fakeClient{}))
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	cmd.SetArgs([]string{"--input", "*"})
 	err := cmd.Execute()
 	assert.ErrorContains(t, err, expectedError)
@@ -89,12 +94,15 @@ func TestNewLoadCommandSuccess(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(&fakeClient{imageLoadFunc: tc.imageLoadFunc})
-		cmd := NewLoadCommand(cli)
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		err := cmd.Execute()
-		assert.NilError(t, err)
-		golden.Assert(t, cli.OutBuffer().String(), fmt.Sprintf("load-command-success.%s.golden", tc.name))
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{imageLoadFunc: tc.imageLoadFunc})
+			cmd := NewLoadCommand(cli)
+			cmd.SetOut(io.Discard)
+			cmd.SetArgs(tc.args)
+			err := cmd.Execute()
+			assert.NilError(t, err)
+			golden.Assert(t, cli.OutBuffer().String(), fmt.Sprintf("load-command-success.%s.golden", tc.name))
+		})
 	}
 }

cli/command/image/prune_test.go

@@ -39,12 +39,16 @@ func TestNewPruneCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cmd := NewPruneCommand(test.NewFakeCli(&fakeClient{
-			imagesPruneFunc: tc.imagesPruneFunc,
-		}))
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := NewPruneCommand(test.NewFakeCli(&fakeClient{
+				imagesPruneFunc: tc.imagesPruneFunc,
+			}))
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 
@@ -94,6 +98,7 @@ func TestNewPruneCommandSuccess(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
+		tc := tc
 		t.Run(tc.name, func(t *testing.T) {
 			cli := test.NewFakeCli(&fakeClient{imagesPruneFunc: tc.imagesPruneFunc})
 			// when prompted, answer "Y" to confirm the prune.
@@ -119,5 +124,8 @@ func TestPrunePromptTermination(t *testing.T) {
 		},
 	})
 	cmd := NewPruneCommand(cli)
+	cmd.SetArgs([]string{})
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	test.TerminatePrompt(ctx, t, cmd, cli)
 }

cli/command/image/pull.go

@@ -50,6 +50,8 @@ func NewPullCommand(dockerCli command.Cli) *cobra.Command {
 	command.AddPlatformFlag(flags, &opts.platform)
 	command.AddTrustVerificationFlags(flags, &opts.untrusted, dockerCli.ContentTrustEnabled())
 
+	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
+
 	return cmd
 }
 

cli/command/image/pull_test.go

@@ -38,11 +38,15 @@ func TestNewPullCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(&fakeClient{})
-		cmd := NewPullCommand(cli)
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{})
+			cmd := NewPullCommand(cli)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 
@@ -69,18 +73,22 @@ func TestNewPullCommandSuccess(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(&fakeClient{
-			imagePullFunc: func(ref string, options image.PullOptions) (io.ReadCloser, error) {
-				assert.Check(t, is.Equal(tc.expectedTag, ref), tc.name)
-				return io.NopCloser(strings.NewReader("")), nil
-			},
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{
+				imagePullFunc: func(ref string, options image.PullOptions) (io.ReadCloser, error) {
+					assert.Check(t, is.Equal(tc.expectedTag, ref), tc.name)
+					return io.NopCloser(strings.NewReader("")), nil
+				},
+			})
+			cmd := NewPullCommand(cli)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			err := cmd.Execute()
+			assert.NilError(t, err)
+			golden.Assert(t, cli.OutBuffer().String(), fmt.Sprintf("pull-command-success.%s.golden", tc.name))
 		})
-		cmd := NewPullCommand(cli)
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		err := cmd.Execute()
-		assert.NilError(t, err)
-		golden.Assert(t, cli.OutBuffer().String(), fmt.Sprintf("pull-command-success.%s.golden", tc.name))
 	}
 }
 
@@ -111,16 +119,20 @@ func TestNewPullCommandWithContentTrustErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(&fakeClient{
-			imagePullFunc: func(ref string, options image.PullOptions) (io.ReadCloser, error) {
-				return io.NopCloser(strings.NewReader("")), errors.New("shouldn't try to pull image")
-			},
-		}, test.EnableContentTrust)
-		cli.SetNotaryClient(tc.notaryFunc)
-		cmd := NewPullCommand(cli)
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		err := cmd.Execute()
-		assert.ErrorContains(t, err, tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{
+				imagePullFunc: func(ref string, options image.PullOptions) (io.ReadCloser, error) {
+					return io.NopCloser(strings.NewReader("")), errors.New("shouldn't try to pull image")
+				},
+			}, test.EnableContentTrust)
+			cli.SetNotaryClient(tc.notaryFunc)
+			cmd := NewPullCommand(cli)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			err := cmd.Execute()
+			assert.ErrorContains(t, err, tc.expectedError)
+		})
 	}
 }

cli/command/image/push.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package image
 
@@ -8,7 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
-	"os"
+	"strings"
 
 	"github.com/containerd/platforms"
 	"github.com/distribution/reference"
@@ -58,11 +58,18 @@ func NewPushCommand(dockerCli command.Cli) *cobra.Command {
 	flags.BoolVarP(&opts.all, "all-tags", "a", false, "Push all tags of an image to the repository")
 	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Suppress verbose output")
 	command.AddTrustSigningFlags(flags, &opts.untrusted, dockerCli.ContentTrustEnabled())
-	flags.StringVar(&opts.platform, "platform", os.Getenv("DOCKER_DEFAULT_PLATFORM"),
+
+	// Don't default to DOCKER_DEFAULT_PLATFORM env variable, always default to
+	// pushing the image as-is. This also avoids forcing the platform selection
+	// on older APIs which don't support it.
+	flags.StringVar(&opts.platform, "platform", "",
 		`Push a platform-specific manifest as a single-platform image to the registry.
+Image index won't be pushed, meaning that other manifests, including attestations won't be preserved.
 'os[/arch[/variant]]': Explicit platform (eg. linux/amd64)`)
 	flags.SetAnnotation("platform", "version", []string{"1.46"})
 
+	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms)
+
 	return cmd
 }
 
@@ -79,9 +86,9 @@ func RunPush(ctx context.Context, dockerCli command.Cli, opts pushOptions) error
 		}
 		platform = &p
 
-		printNote(dockerCli, `Selecting a single platform will only push one matching image manifest from a multi-platform image index.
-This means that any other components attached to the multi-platform image index (like Buildkit attestations) won't be pushed.
-If you want to only push a single platform image while preserving the attestations, please use 'docker convert\n'
+		printNote(dockerCli, `Using --platform pushes only the specified platform manifest of a multi-platform image index.
+Other components, like attestations, will not be included.
+To push the complete multi-platform image, remove the --platform flag.
 `)
 	}
 
@@ -179,9 +186,22 @@ func handleAux(dockerCli command.Cli) func(jm jsonmessage.JSONMessage) {
 
 func printNote(dockerCli command.Cli, format string, args ...any) {
 	if dockerCli.Err().IsTerminal() {
-		_, _ = fmt.Fprint(dockerCli.Err(), aec.WhiteF.Apply(aec.CyanB.Apply("[ NOTE ]"))+" ")
-	} else {
-		_, _ = fmt.Fprint(dockerCli.Err(), "[ NOTE ] ")
+		format = strings.ReplaceAll(format, "--platform", aec.Bold.Apply("--platform"))
+	}
+
+	header := " Info -> "
+	padding := len(header)
+	if dockerCli.Err().IsTerminal() {
+		padding = len("i Info > ")
+		header = aec.Bold.Apply(aec.LightCyanB.Apply(aec.BlackF.Apply("i")) + " " + aec.LightCyanF.Apply("Info → "))
+	}
+
+	_, _ = fmt.Fprint(dockerCli.Err(), header)
+	s := fmt.Sprintf(format, args...)
+	for idx, line := range strings.Split(s, "\n") {
+		if idx > 0 {
+			_, _ = fmt.Fprint(dockerCli.Err(), strings.Repeat(" ", padding))
+		}
+		_, _ = fmt.Fprintln(dockerCli.Err(), aec.Italic.Apply(line))
 	}
-	_, _ = fmt.Fprintf(dockerCli.Err(), aec.Bold.Apply(format)+"\n", args...)
 }

cli/command/image/push_test.go

@@ -38,11 +38,15 @@ func TestNewPushCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(&fakeClient{imagePushFunc: tc.imagePushFunc})
-		cmd := NewPushCommand(cli)
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{imagePushFunc: tc.imagePushFunc})
+			cmd := NewPushCommand(cli)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 
@@ -73,6 +77,7 @@ func TestNewPushCommandSuccess(t *testing.T) {
 			})
 			cmd := NewPushCommand(cli)
 			cmd.SetOut(cli.OutBuffer())
+			cmd.SetErr(io.Discard)
 			cmd.SetArgs(tc.args)
 			assert.NilError(t, cmd.Execute())
 			if tc.output != "" {

cli/command/image/remove.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli/command"
+	"github.com/docker/cli/cli/command/completion"
 	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/errdefs"
 	"github.com/pkg/errors"
@@ -29,6 +30,7 @@ func NewRemoveCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runRemove(cmd.Context(), dockerCli, opts, args)
 		},
+		ValidArgsFunction: completion.ImageNames(dockerCli),
 		Annotations: map[string]string{
 			"aliases": "docker image rm, docker image remove, docker rmi",
 		},

cli/command/image/remove_test.go

@@ -62,11 +62,13 @@ func TestNewRemoveCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
+		tc := tc
 		t.Run(tc.name, func(t *testing.T) {
 			cmd := NewRemoveCommand(test.NewFakeCli(&fakeClient{
 				imageRemoveFunc: tc.imageRemoveFunc,
 			}))
 			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
 			cmd.SetArgs(tc.args)
 			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 		})
@@ -119,10 +121,12 @@ func TestNewRemoveCommandSuccess(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
+		tc := tc
 		t.Run(tc.name, func(t *testing.T) {
 			cli := test.NewFakeCli(&fakeClient{imageRemoveFunc: tc.imageRemoveFunc})
 			cmd := NewRemoveCommand(cli)
 			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
 			cmd.SetArgs(tc.args)
 			assert.NilError(t, cmd.Execute())
 			assert.Check(t, is.Equal(tc.expectedStderr, cli.ErrBuffer().String()))

cli/command/image/save_test.go

@@ -52,12 +52,16 @@ func TestNewSaveCommandErrors(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(&fakeClient{imageSaveFunc: tc.imageSaveFunc})
-		cli.Out().SetIsTerminal(tc.isTerminal)
-		cmd := NewSaveCommand(cli)
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			cli := test.NewFakeCli(&fakeClient{imageSaveFunc: tc.imageSaveFunc})
+			cli.Out().SetIsTerminal(tc.isTerminal)
+			cmd := NewSaveCommand(cli)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 
@@ -77,7 +81,7 @@ func TestNewSaveCommandSuccess(t *testing.T) {
 				return io.NopCloser(strings.NewReader("")), nil
 			},
 			deferredFunc: func() {
-				os.Remove("save_tmp_file")
+				_ = os.Remove("save_tmp_file")
 			},
 		},
 		{
@@ -92,16 +96,20 @@ func TestNewSaveCommandSuccess(t *testing.T) {
 		},
 	}
 	for _, tc := range testCases {
-		cmd := NewSaveCommand(test.NewFakeCli(&fakeClient{
-			imageSaveFunc: func(images []string) (io.ReadCloser, error) {
-				return io.NopCloser(strings.NewReader("")), nil
-			},
-		}))
-		cmd.SetOut(io.Discard)
-		cmd.SetArgs(tc.args)
-		assert.NilError(t, cmd.Execute())
-		if tc.deferredFunc != nil {
-			tc.deferredFunc()
-		}
+		tc := tc
+		t.Run(strings.Join(tc.args, " "), func(t *testing.T) {
+			cmd := NewSaveCommand(test.NewFakeCli(&fakeClient{
+				imageSaveFunc: func(images []string) (io.ReadCloser, error) {
+					return io.NopCloser(strings.NewReader("")), nil
+				},
+			}))
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(tc.args)
+			assert.NilError(t, cmd.Execute())
+			if tc.deferredFunc != nil {
+				tc.deferredFunc()
+			}
+		})
 	}
 }

cli/command/image/tag_test.go

@@ -20,6 +20,7 @@ func TestCliNewTagCommandErrors(t *testing.T) {
 		cmd := NewTagCommand(test.NewFakeCli(&fakeClient{}))
 		cmd.SetArgs(args)
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), expectedError)
 	}
 }

cli/command/image/tree.go

@@ -0,0 +1,393 @@
+package image
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/containerd/platforms"
+	"github.com/docker/cli/cli/command"
+	"github.com/docker/cli/cli/streams"
+	"github.com/docker/docker/api/types/filters"
+	imagetypes "github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/pkg/stringid"
+	"github.com/docker/go-units"
+	"github.com/morikuni/aec"
+)
+
+type treeOptions struct {
+	all     bool
+	filters filters.Args
+}
+
+type treeView struct {
+	images []topImage
+
+	// imageSpacing indicates whether there should be extra spacing between images.
+	imageSpacing bool
+}
+
+func runTree(ctx context.Context, dockerCLI command.Cli, opts treeOptions) error {
+	images, err := dockerCLI.Client().ImageList(ctx, imagetypes.ListOptions{
+		All:       opts.all,
+		Filters:   opts.filters,
+		Manifests: true,
+	})
+	if err != nil {
+		return err
+	}
+
+	view := treeView{
+		images: make([]topImage, 0, len(images)),
+	}
+	for _, img := range images {
+		details := imageDetails{
+			ID:        img.ID,
+			DiskUsage: units.HumanSizeWithPrecision(float64(img.Size), 3),
+			InUse:     img.Containers > 0,
+		}
+
+		var totalContent int64
+		children := make([]subImage, 0, len(img.Manifests))
+		for _, im := range img.Manifests {
+			if im.Kind != imagetypes.ManifestKindImage {
+				continue
+			}
+
+			im := im
+			sub := subImage{
+				Platform:  platforms.Format(im.ImageData.Platform),
+				Available: im.Available,
+				Details: imageDetails{
+					ID:          im.ID,
+					DiskUsage:   units.HumanSizeWithPrecision(float64(im.Size.Total), 3),
+					InUse:       len(im.ImageData.Containers) > 0,
+					ContentSize: units.HumanSizeWithPrecision(float64(im.Size.Content), 3),
+				},
+			}
+
+			if sub.Details.InUse {
+				// Mark top-level parent image as used if any of its subimages are used.
+				details.InUse = true
+			}
+
+			totalContent += im.Size.Content
+			children = append(children, sub)
+
+			// Add extra spacing between images if there's at least one entry with children.
+			view.imageSpacing = true
+		}
+
+		details.ContentSize = units.HumanSizeWithPrecision(float64(totalContent), 3)
+
+		view.images = append(view.images, topImage{
+			Names:    img.RepoTags,
+			Details:  details,
+			Children: children,
+			created:  img.Created,
+		})
+	}
+
+	sort.Slice(view.images, func(i, j int) bool {
+		return view.images[i].created > view.images[j].created
+	})
+
+	return printImageTree(dockerCLI, view)
+}
+
+type imageDetails struct {
+	ID          string
+	DiskUsage   string
+	InUse       bool
+	ContentSize string
+}
+
+type topImage struct {
+	Names    []string
+	Details  imageDetails
+	Children []subImage
+
+	created int64
+}
+
+type subImage struct {
+	Platform  string
+	Available bool
+	Details   imageDetails
+}
+
+const columnSpacing = 3
+
+func printImageTree(dockerCLI command.Cli, view treeView) error {
+	out := dockerCLI.Out()
+	_, width := out.GetTtySize()
+	if width == 0 {
+		width = 80
+	}
+	if width < 20 {
+		width = 20
+	}
+
+	warningColor := aec.LightYellowF
+	headerColor := aec.NewBuilder(aec.DefaultF, aec.Bold).ANSI
+	topNameColor := aec.NewBuilder(aec.BlueF, aec.Bold).ANSI
+	normalColor := aec.NewBuilder(aec.DefaultF).ANSI
+	greenColor := aec.NewBuilder(aec.GreenF).ANSI
+	untaggedColor := aec.NewBuilder(aec.Faint).ANSI
+	if !out.IsTerminal() {
+		headerColor = noColor{}
+		topNameColor = noColor{}
+		normalColor = noColor{}
+		greenColor = noColor{}
+		warningColor = noColor{}
+		untaggedColor = noColor{}
+	}
+
+	_, _ = fmt.Fprintln(out, warningColor.Apply("WARNING: This is an experimental feature. The output may change and shouldn't be depended on."))
+	_, _ = fmt.Fprintln(out, "")
+
+	columns := []imgColumn{
+		{
+			Title: "Image",
+			Align: alignLeft,
+			Width: 0,
+		},
+		{
+			Title: "ID",
+			Align: alignLeft,
+			Width: 12,
+			DetailsValue: func(d *imageDetails) string {
+				return stringid.TruncateID(d.ID)
+			},
+		},
+		{
+			Title: "Disk usage",
+			Align: alignRight,
+			Width: 10,
+			DetailsValue: func(d *imageDetails) string {
+				return d.DiskUsage
+			},
+		},
+		{
+			Title: "Content size",
+			Align: alignRight,
+			Width: 12,
+			DetailsValue: func(d *imageDetails) string {
+				return d.ContentSize
+			},
+		},
+		{
+			Title: "In Use",
+			Align: alignCenter,
+			Width: 6,
+			Color: &greenColor,
+			DetailsValue: func(d *imageDetails) string {
+				if d.InUse {
+					return "✔"
+				}
+				return " "
+			},
+		},
+	}
+
+	nameWidth := int(width)
+	for idx, h := range columns {
+		if h.Width == 0 {
+			continue
+		}
+		d := h.Width
+		if idx > 0 {
+			d += columnSpacing
+		}
+		// If the first column gets too short, remove remaining columns
+		if nameWidth-d < 12 {
+			columns = columns[:idx]
+			break
+		}
+		nameWidth -= d
+	}
+
+	images := view.images
+	// Try to make the first column as narrow as possible
+	widest := widestFirstColumnValue(columns, images)
+	if nameWidth > widest {
+		nameWidth = widest
+	}
+	columns[0].Width = nameWidth
+
+	// Print columns
+	for i, h := range columns {
+		if i > 0 {
+			_, _ = fmt.Fprint(out, strings.Repeat(" ", columnSpacing))
+		}
+
+		_, _ = fmt.Fprint(out, h.Print(headerColor, strings.ToUpper(h.Title)))
+	}
+
+	_, _ = fmt.Fprintln(out)
+
+	// Print images
+	for _, img := range images {
+		printNames(out, columns, img, topNameColor, untaggedColor)
+		printDetails(out, columns, normalColor, img.Details)
+
+		if len(img.Children) > 0 || view.imageSpacing {
+			_, _ = fmt.Fprintln(out)
+		}
+		printChildren(out, columns, img, normalColor)
+		_, _ = fmt.Fprintln(out)
+	}
+
+	return nil
+}
+
+func printDetails(out *streams.Out, headers []imgColumn, defaultColor aec.ANSI, details imageDetails) {
+	for _, h := range headers {
+		if h.DetailsValue == nil {
+			continue
+		}
+
+		_, _ = fmt.Fprint(out, strings.Repeat(" ", columnSpacing))
+		clr := defaultColor
+		if h.Color != nil {
+			clr = *h.Color
+		}
+		val := h.DetailsValue(&details)
+		_, _ = fmt.Fprint(out, h.Print(clr, val))
+	}
+}
+
+func printChildren(out *streams.Out, headers []imgColumn, img topImage, normalColor aec.ANSI) {
+	for idx, sub := range img.Children {
+		clr := normalColor
+		if !sub.Available {
+			clr = normalColor.With(aec.Faint)
+		}
+
+		if idx != len(img.Children)-1 {
+			_, _ = fmt.Fprint(out, headers[0].Print(clr, "├─ "+sub.Platform))
+		} else {
+			_, _ = fmt.Fprint(out, headers[0].Print(clr, "└─ "+sub.Platform))
+		}
+
+		printDetails(out, headers, clr, sub.Details)
+		_, _ = fmt.Fprintln(out, "")
+	}
+}
+
+func printNames(out *streams.Out, headers []imgColumn, img topImage, color, untaggedColor aec.ANSI) {
+	if len(img.Names) == 0 {
+		_, _ = fmt.Fprint(out, headers[0].Print(untaggedColor, "<untagged>"))
+	}
+
+	for nameIdx, name := range img.Names {
+		if nameIdx != 0 {
+			_, _ = fmt.Fprintln(out, "")
+		}
+		_, _ = fmt.Fprint(out, headers[0].Print(color, name))
+	}
+}
+
+type alignment int
+
+const (
+	alignLeft alignment = iota
+	alignCenter
+	alignRight
+)
+
+type imgColumn struct {
+	Title string
+	Width int
+	Align alignment
+
+	DetailsValue func(*imageDetails) string
+	Color        *aec.ANSI
+}
+
+func truncateRunes(s string, length int) string {
+	runes := []rune(s)
+	if len(runes) > length {
+		return string(runes[:length-3]) + "..."
+	}
+	return s
+}
+
+func (h imgColumn) Print(clr aec.ANSI, s string) string {
+	switch h.Align {
+	case alignCenter:
+		return h.PrintC(clr, s)
+	case alignRight:
+		return h.PrintR(clr, s)
+	case alignLeft:
+	}
+	return h.PrintL(clr, s)
+}
+
+func (h imgColumn) PrintC(clr aec.ANSI, s string) string {
+	ln := utf8.RuneCountInString(s)
+
+	if ln > h.Width {
+		return clr.Apply(truncateRunes(s, h.Width))
+	}
+
+	fill := h.Width - ln
+
+	l := fill / 2
+	r := fill - l
+
+	return strings.Repeat(" ", l) + clr.Apply(s) + strings.Repeat(" ", r)
+}
+
+func (h imgColumn) PrintL(clr aec.ANSI, s string) string {
+	ln := utf8.RuneCountInString(s)
+	if ln > h.Width {
+		return clr.Apply(truncateRunes(s, h.Width))
+	}
+
+	return clr.Apply(s) + strings.Repeat(" ", h.Width-ln)
+}
+
+func (h imgColumn) PrintR(clr aec.ANSI, s string) string {
+	ln := utf8.RuneCountInString(s)
+	if ln > h.Width {
+		return clr.Apply(truncateRunes(s, h.Width))
+	}
+
+	return strings.Repeat(" ", h.Width-ln) + clr.Apply(s)
+}
+
+type noColor struct{}
+
+func (a noColor) With(_ ...aec.ANSI) aec.ANSI {
+	return a
+}
+
+func (a noColor) Apply(s string) string {
+	return s
+}
+
+func (a noColor) String() string {
+	return ""
+}
+
+// widestFirstColumnValue calculates the width needed to fully display the image names and platforms.
+func widestFirstColumnValue(headers []imgColumn, images []topImage) int {
+	width := len(headers[0].Title)
+	for _, img := range images {
+		for _, name := range img.Names {
+			if len(name) > width {
+				width = len(name)
+			}
+		}
+		for _, sub := range img.Children {
+			pl := len(sub.Platform) + len("└─ ")
+			if pl > width {
+				width = pl
+			}
+		}
+	}
+	return width
+}

cli/command/inspect/inspector.go

@@ -1,5 +1,5 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
-//go:build go1.21
+//go:build go1.22
 
 package inspect
 

cli/command/manifest/annotate_test.go

@@ -35,6 +35,7 @@ func TestManifestAnnotateError(t *testing.T) {
 		cmd := newAnnotateCommand(cli)
 		cmd.SetArgs(tc.args)
 		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
 		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
 	}
 }
@@ -52,6 +53,7 @@ func TestManifestAnnotate(t *testing.T) {
 	cmd := newAnnotateCommand(cli)
 	cmd.SetArgs([]string{"example.com/list:v1", "example.com/fake:0.0"})
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	expectedError := "manifest for image example.com/fake:0.0 does not exist"
 	assert.ErrorContains(t, cmd.Execute(), expectedError)
 
@@ -71,6 +73,7 @@ func TestManifestAnnotate(t *testing.T) {
 	err = cmd.Flags().Set("verbose", "true")
 	assert.NilError(t, err)
 	cmd.SetArgs([]string{"example.com/list:v1", "example.com/alpine:3.0"})
+	cmd.SetErr(io.Discard)
 	assert.NilError(t, cmd.Execute())
 	actual := cli.OutBuffer()
 	expected := golden.Get(t, "inspect-annotate.golden")

cli/command/manifest/cmd.go

@@ -18,7 +18,7 @@ func NewManifestCommand(dockerCli command.Cli) *cobra.Command {
 		Long:  manifestDescription,
 		Args:  cli.NoArgs,
 		Run: func(cmd *cobra.Command, args []string) {
-			fmt.Fprintf(dockerCli.Err(), "\n"+cmd.UsageString())
+			_, _ = fmt.Fprint(dockerCli.Err(), "\n"+cmd.UsageString())
 		},
 		Annotations: map[string]string{"experimentalCLI": ""},
 	}

cli/command/manifest/create_test.go

@@ -31,11 +31,15 @@ func TestManifestCreateErrors(t *testing.T) {
 	}
 
 	for _, tc := range testCases {
-		cli := test.NewFakeCli(nil)
-		cmd := newCreateListCommand(cli)
-		cmd.SetArgs(tc.args)
-		cmd.SetOut(io.Discard)
-		assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		tc := tc
+		t.Run(tc.expectedError, func(t *testing.T) {
+			cli := test.NewFakeCli(nil)
+			cmd := newCreateListCommand(cli)
+			cmd.SetArgs(tc.args)
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			assert.ErrorContains(t, cmd.Execute(), tc.expectedError)
+		})
 	}
 }
 
@@ -87,6 +91,7 @@ func TestManifestCreateRefuseAmend(t *testing.T) {
 	cmd := newCreateListCommand(cli)
 	cmd.SetArgs([]string{"example.com/list:v1", "example.com/alpine:3.0"})
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	err = cmd.Execute()
 	assert.Error(t, err, "refusing to amend an existing manifest list with no --amend flag")
 }
@@ -109,6 +114,7 @@ func TestManifestCreateNoManifest(t *testing.T) {
 	cmd := newCreateListCommand(cli)
 	cmd.SetArgs([]string{"example.com/list:v1", "example.com/alpine:3.0"})
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	err := cmd.Execute()
 	assert.Error(t, err, "No such image: example.com/alpine:3.0")
 }

cli/command/manifest/inspect_test.go

@@ -70,6 +70,7 @@ func TestInspectCommandLocalManifestNotFound(t *testing.T) {
 
 	cmd := newInspectCommand(cli)
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	cmd.SetArgs([]string{"example.com/list:v1", "example.com/alpine:3.0"})
 	err := cmd.Execute()
 	assert.Error(t, err, "No such manifest: example.com/alpine:3.0")
@@ -91,6 +92,7 @@ func TestInspectCommandNotFound(t *testing.T) {
 
 	cmd := newInspectCommand(cli)
 	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
 	cmd.SetArgs([]string{"example.com/alpine:3.0"})
 	err := cmd.Execute()
 	assert.Error(t, err, "No such manifest: example.com/alpine:3.0")