Merge pull request #5566 from austinvazquez/cherry-pick-baceb4b1586f38b9d6c031ab0a696f32c52852f3-to-25.0

[25.0 backport] docs, man: dockerd: add documentation for "--log-format" option

.github/PULL_REQUEST_TEMPLATE.md

@@ -22,9 +22,13 @@ Please provide the following information:
 **- Description for the changelog**
 <!--
 Write a short (one line) summary that describes the changes in this
-pull request for inclusion in the changelog:
+pull request for inclusion in the changelog.
+It must be placed inside the below triple backticks section:
 -->
+```markdown changelog
 
 
+```
+
 **- A picture of a cute animal (not mandatory but encouraged)**
 

.github/workflows/build.yml

@@ -1,9 +1,21 @@
 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
 
+env:
+  VERSION: ${{ github.ref }}
+
 on:
   workflow_dispatch:
   push:
@@ -16,7 +28,7 @@ on:
 
 jobs:
   prepare:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     outputs:
       matrix: ${{ steps.platforms.outputs.matrix }}
     steps:
@@ -34,7 +46,7 @@ jobs:
           echo ${{ steps.platforms.outputs.matrix }}
 
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     needs:
       - prepare
     strategy:
@@ -74,20 +86,64 @@ jobs:
           platformPair=${platform//\//-}
           tar -cvzf "/tmp/out/docker-${platformPair}.tar.gz" .
           if [ -z "${{ matrix.use_glibc }}" ]; then
-            echo "ARTIFACT_NAME=${{ matrix.target }}" >> $GITHUB_ENV
+            echo "ARTIFACT_NAME=${{ matrix.target }}-${platformPair}" >> $GITHUB_ENV
           else
-            echo "ARTIFACT_NAME=${{ matrix.target }}-glibc" >> $GITHUB_ENV
+            echo "ARTIFACT_NAME=${{ matrix.target }}-${platformPair}-glibc" >> $GITHUB_ENV
           fi
       -
         name: Upload artifacts
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: ${{ env.ARTIFACT_NAME }}
           path: /tmp/out/*
           if-no-files-found: error
 
+  bin-image:
+    runs-on: ubuntu-22.04
+    if: ${{ github.event_name != 'pull_request' && github.repository == 'docker/cli' }}
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      -
+        name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: dockereng/cli-bin
+          tags: |
+            type=semver,pattern={{version}}
+            type=ref,event=branch
+            type=ref,event=pr
+            type=sha
+      -
+        name: Login to DockerHub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_CLIBIN_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_CLIBIN_TOKEN }}
+      -
+        name: Build and push image
+        uses: docker/bake-action@v4
+        with:
+          files: |
+            ./docker-bake.hcl
+            ${{ steps.meta.outputs.bake-file }}
+          targets: bin-image-cross
+          push: ${{ github.event_name != 'pull_request' }}
+          set: |
+            *.cache-from=type=gha,scope=bin-image
+            *.cache-to=type=gha,scope=bin-image,mode=max
+
   prepare-plugins:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     outputs:
       matrix: ${{ steps.platforms.outputs.matrix }}
     steps:
@@ -105,7 +161,7 @@ jobs:
           echo ${{ steps.platforms.outputs.matrix }}
 
   plugins:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     needs:
       - prepare-plugins
     strategy:

.github/workflows/codeql.yml

@@ -1,5 +1,14 @@
 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: 
@@ -26,6 +35,8 @@ jobs:
   codeql:
     runs-on: 'ubuntu-latest'
     timeout-minutes: 360
+    env:
+      DISABLE_WARN_OUTSIDE_CONTAINER: '1'
     permissions:
       actions: read
       contents: read
@@ -46,17 +57,27 @@ jobs:
         name: Update Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.21'
+          go-version: 1.22.8
       -
         name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
           languages: go
+      # CodeQL 2.16.4's auto-build added support for multi-module repositories,
+      # and is trying to be smart by searching for modules in every directory,
+      # including vendor directories. If no module is found, it's creating one
+      # which is ... not what we want, so let's give it a "go.mod".
+      # see: https://github.com/docker/cli/pull/4944#issuecomment-2002034698
+      -
+        name: Create go.mod
+        run: |
+          ln -s vendor.mod go.mod
+          ln -s vendor.sum go.sum
       -
         name: Autobuild
-        uses: github/codeql-action/autobuild@v2
+        uses: github/codeql-action/autobuild@v3
       -
         name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3
         with:
           category: "/language:go"

.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
@@ -16,7 +25,7 @@ on:
 
 jobs:
   e2e:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     strategy:
       fail-fast: false
       matrix:
@@ -28,11 +37,11 @@ jobs:
           - alpine
           - debian
         engine-version:
-#          - 20.10-dind # FIXME: Fails on 20.10
-          - stable-dind # TODO: Use 20.10-dind, stable-dind is deprecated
-        include:
-          - target: non-experimental
-            engine-version: 19.03-dind
+          - 25.0  # latest
+          - 24.0  # 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
     steps:
       -
         name: Checkout
@@ -55,10 +64,10 @@ jobs:
           make -f docker.Makefile test-e2e-${{ matrix.target }}
         env:
           BASE_VARIANT: ${{ matrix.base }}
-          E2E_ENGINE_VERSION: ${{ matrix.engine-version }}
+          ENGINE_VERSION: ${{ matrix.engine-version }}
           TESTFLAGS: -coverprofile=/tmp/coverage/coverage.txt
       -
         name: Send to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           file: ./build/coverage/coverage.txt

.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
@@ -16,7 +25,7 @@ on:
 
 jobs:
   ctn:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       -
         name: Checkout
@@ -31,7 +40,7 @@ jobs:
           targets: test-coverage
       -
         name: Send to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           file: ./build/coverage/coverage.txt
 
@@ -45,7 +54,7 @@ jobs:
       fail-fast: false
       matrix:
         os:
-          - macos-11
+          - macos-12
 #          - 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:
       -
@@ -63,7 +72,7 @@ jobs:
         name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: 1.21.5
+          go-version: 1.22.8
       -
         name: Test
         run: |
@@ -73,7 +82,7 @@ jobs:
         shell: bash
       -
         name: Send to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         with:
           file: /tmp/coverage.txt
           working-directory: ${{ env.GOPATH }}/src/github.com/docker/cli

.github/workflows/validate-pr.yml

@@ -0,0 +1,71 @@
+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]
+
+jobs:
+  check-area-label:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Missing `area/` label
+        if: contains(join(github.event.pull_request.labels.*.name, ','), 'impact/') && !contains(join(github.event.pull_request.labels.*.name, ','), 'area/')
+        run: |
+          echo "::error::Every PR with an 'impact/*' label should also have an 'area/*' label"
+          exit 1
+      - name: OK
+        run: exit 0
+
+  check-changelog:
+    if: contains(join(github.event.pull_request.labels.*.name, ','), 'impact/')
+    runs-on: ubuntu-20.04
+    env:
+      PR_BODY: |
+        ${{ github.event.pull_request.body }}
+    steps:
+      - name: Check changelog description
+        run: |
+          # Extract the `markdown changelog` note code block
+          block=$(echo -n "$PR_BODY" | tr -d '\r' | awk '/^```markdown changelog$/{flag=1;next}/^```$/{flag=0}flag')
+
+          # Strip empty lines
+          desc=$(echo "$block" |  awk NF)
+
+          if [ -z "$desc" ]; then
+            echo "::error::Changelog section is empty. Please provide a description for the changelog."
+            exit 1
+          fi
+
+          len=$(echo -n "$desc" | wc -c)
+          if [[ $len -le 6 ]]; then
+            echo "::error::Description looks too short: $desc"
+            exit 1
+          fi
+
+          echo "This PR will be included in the release notes with the following note:"
+          echo "$desc"
+
+  check-pr-branch:
+    runs-on: ubuntu-20.04
+    env:
+      PR_TITLE: ${{ github.event.pull_request.title }}
+    steps:
+      # 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

.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
@@ -16,7 +25,7 @@ on:
 
 jobs:
   validate:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     strategy:
       fail-fast: false
       matrix:
@@ -37,7 +46,7 @@ jobs:
 
   # check that the generated Markdown and the checked-in files match
   validate-md:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
       -
         name: Checkout
@@ -57,7 +66,7 @@ jobs:
           fi
 
   validate-make:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     strategy:
       fail-fast: false
       matrix:

.mailmap

@@ -31,10 +31,10 @@ Aleksandrs Fadins <aleks@s-ko.net>
 Alessandro Boch <aboch@tetrationanalytics.com> <aboch@docker.com>
 Alex Chen <alexchenunix@gmail.com> <root@localhost.localdomain>
 Alex Ellis <alexellis2@gmail.com>
+Alexander Chneerov <achneerov@gmail.com>
 Alexander Larsson <alexl@redhat.com> <alexander.larsson@gmail.com>
 Alexander Morozov <lk4d4math@gmail.com>
 Alexander Morozov <lk4d4math@gmail.com> <lk4d4@docker.com>
-Alexander Chneerov <achneerov@gmail.com>
 Alexandre Beslic <alexandre.beslic@gmail.com> <abronan@docker.com>
 Alexis Couvreur <alexiscouvreur.pro@gmail.com>
 Alicia Lauerman <alicia@eta.im> <allydevour@me.com>
@@ -76,8 +76,8 @@ Bin Liu <liubin0329@gmail.com>
 Bin Liu <liubin0329@gmail.com> <liubin0329@users.noreply.github.com>
 Bingshen Wang <bingshen.wbs@alibaba-inc.com>
 Bjorn Neergaard <bjorn.neergaard@docker.com>
-Bjorn Neergaard <bjorn.neergaard@docker.com> <bneergaard@mirantis.com>
 Bjorn Neergaard <bjorn.neergaard@docker.com> <bjorn@neersighted.com>
+Bjorn Neergaard <bjorn.neergaard@docker.com> <bneergaard@mirantis.com>
 Boaz Shuster <ripcurld.github@gmail.com>
 Brad Baker <brad@brad.fi>
 Brad Baker <brad@brad.fi> <88946291+brdbkr@users.noreply.github.com>
@@ -98,6 +98,8 @@ Chen Chuanliang <chen.chuanliang@zte.com.cn>
 Chen Mingjie <chenmingjie0828@163.com>
 Chen Qiu <cheney-90@hotmail.com>
 Chen Qiu <cheney-90@hotmail.com> <21321229@zju.edu.cn>
+Chris Chinchilla <chris@chrischinchilla.com>
+Chris Chinchilla <chris@chrischinchilla.com> <chris.ward@docker.com>
 Chris Dias <cdias@microsoft.com>
 Chris McKinnel <chris.mckinnel@tangentlabs.co.uk>
 Christopher Biscardi <biscarch@sketcht.com>
@@ -118,11 +120,11 @@ Daehyeok Mun <daehyeok@gmail.com> <daehyeok@daehyeok-ui-MacBook-Air.local>
 Daehyeok Mun <daehyeok@gmail.com> <daehyeok@daehyeokui-MacBook-Air.local>
 Daisuke Ito <itodaisuke00@gmail.com>
 Dan Feldman <danf@jfrog.com>
+Danial Gharib <danial.mail.gh@gmail.com>
 Daniel Dao <dqminh@cloudflare.com>
 Daniel Dao <dqminh@cloudflare.com> <dqminh89@gmail.com>
 Daniel Garcia <daniel@danielgarcia.info>
 Daniel Gasienica <daniel@gasienica.ch> <dgasienica@zynga.com>
-Danial Gharib <danial.mail.gh@gmail.com>
 Daniel Goosen <daniel.goosen@surveysampling.com> <djgoosen@users.noreply.github.com>
 Daniel Grunwell <mwgrunny@gmail.com>
 Daniel J Walsh <dwalsh@redhat.com>
@@ -192,6 +194,8 @@ Gerwim Feiken <g.feiken@tfe.nl> <gerwim@gmail.com>
 Giampaolo Mancini <giampaolo@trampolineup.com>
 Gopikannan Venugopalsamy <gopikannan.venugopalsamy@gmail.com>
 Gou Rao <gou@portworx.com> <gourao@users.noreply.github.com>
+Graeme Wiebe <graeme.wiebe@gmail.com>
+Graeme Wiebe <graeme.wiebe@gmail.com> <79593869+TheRealGramdalf@users.noreply.github.com>
 Greg Stephens <greg@udon.org>
 Guillaume J. Charmes <guillaume.charmes@docker.com> <charmes.guillaume@gmail.com>
 Guillaume J. Charmes <guillaume.charmes@docker.com> <guillaume.charmes@dotcloud.com>
@@ -318,6 +322,7 @@ Kyle Mitofsky <Kylemit@gmail.com>
 Lajos Papp <lajos.papp@sequenceiq.com> <lalyos@yahoo.com>
 Lei Jitang <leijitang@huawei.com>
 Lei Jitang <leijitang@huawei.com> <leijitang@gmail.com>
+Li Fu Bang <lifubang@acmcoder.com>
 Liang Mingqiang <mqliang.zju@gmail.com>
 Liang-Chi Hsieh <viirya@gmail.com>
 Liao Qingwei <liaoqingwei@huawei.com>
@@ -412,6 +417,9 @@ Paul Liljenberg <liljenberg.paul@gmail.com> <letters@paulnotcom.se>
 Pavel Tikhomirov <ptikhomirov@virtuozzo.com> <ptikhomirov@parallels.com>
 Pawel Konczalski <mail@konczalski.de>
 Paweł Pokrywka <pepawel@users.noreply.github.com>
+Per Lundberg <perlun@gmail.com>
+Per Lundberg <perlun@gmail.com> <per.lundberg@ecraft.com>
+Per Lundberg <perlun@gmail.com> <per.lundberg@hibox.tv>
 Peter Choi <phkchoi89@gmail.com> <reikani@Peters-MacBook-Pro.local>
 Peter Dave Hello <hsu@peterdavehello.org> <PeterDaveHello@users.noreply.github.com>
 Peter Hsu <shhsu@microsoft.com>
@@ -427,6 +435,8 @@ Qiang Huang <h.huangqiang@huawei.com>
 Qiang Huang <h.huangqiang@huawei.com> <qhuang@10.0.2.15>
 Ray Tsang <rayt@google.com> <saturnism@users.noreply.github.com>
 Renaud Gaubert <rgaubert@nvidia.com> <renaud.gaubert@gmail.com>
+Rob Murray <rob.murray@docker.com>
+Rob Murray <rob.murray@docker.com> <148866618+robmry@users.noreply.github.com>
 Robert Terhaar <rterhaar@atlanticdynamic.com> <robbyt@users.noreply.github.com>
 Roberto G. Hashioka <roberto.hashioka@docker.com> <roberto_hashioka@hotmail.com>
 Roberto Muñoz Fernández <robertomf@gmail.com> <roberto.munoz.fernandez.contractor@bbva.com>

AUTHORS

@@ -145,7 +145,7 @@ Chen Chuanliang <chen.chuanliang@zte.com.cn>
 Chen Hanxiao <chenhanxiao@cn.fujitsu.com>
 Chen Mingjie <chenmingjie0828@163.com>
 Chen Qiu <cheney-90@hotmail.com>
-Chris Chinchilla <chris.ward@docker.com>
+Chris Chinchilla <chris@chrischinchilla.com>
 Chris Couzens <ccouzens@gmail.com>
 Chris Gavin <chris@chrisgavin.me>
 Chris Gibson <chris@chrisg.io>
@@ -306,6 +306,7 @@ Gleb Stsenov <gleb.stsenov@gmail.com>
 Goksu Toprak <goksu.toprak@docker.com>
 Gou Rao <gou@portworx.com>
 Govind Rai <raigovind93@gmail.com>
+Graeme Wiebe <graeme.wiebe@gmail.com>
 Grant Reaber <grant.reaber@gmail.com>
 Greg Pflaum <gpflaum@users.noreply.github.com>
 Gsealy <jiaojingwei1001@hotmail.com>
@@ -329,6 +330,7 @@ Hernan Garcia <hernandanielg@gmail.com>
 Hongbin Lu <hongbin034@gmail.com>
 Hu Keping <hukeping@huawei.com>
 Huayi Zhang <irachex@gmail.com>
+Hugo Chastel <Hugo-C@users.noreply.github.com>
 Hugo Gabriel Eyherabide <hugogabriel.eyherabide@gmail.com>
 huqun <huqun@zju.edu.cn>
 Huu Nguyen <huu@prismskylabs.com>
@@ -486,10 +488,10 @@ Lennie <github@consolejunkie.net>
 Leo Gallucci <elgalu3@gmail.com>
 Leonid Skorospelov <leosko94@gmail.com>
 Lewis Daly <lewisdaly@me.com>
+Li Fu Bang <lifubang@acmcoder.com>
 Li Yi <denverdino@gmail.com>
 Li Yi <weiyuan.yl@alibaba-inc.com>
 Liang-Chi Hsieh <viirya@gmail.com>
-Lifubang <lifubang@acmcoder.com>
 Lihua Tang <lhtang@alauda.io>
 Lily Guo <lily.guo@docker.com>
 Lin Lu <doraalin@163.com>
@@ -646,7 +648,7 @@ Paweł Gronowski <pawel.gronowski@docker.com>
 Paweł Pokrywka <pepawel@users.noreply.github.com>
 Paweł Szczekutowicz <pszczekutowicz@gmail.com>
 Peeyush Gupta <gpeeyush@linux.vnet.ibm.com>
-Per Lundberg <per.lundberg@ecraft.com>
+Per Lundberg <perlun@gmail.com>
 Peter Dave Hello <hsu@peterdavehello.org>
 Peter Edge <peter.edge@gmail.com>
 Peter Hsu <shhsu@microsoft.com>
@@ -669,6 +671,7 @@ Preston Cowley <preston.cowley@sony.com>
 Pure White <daniel48@126.com>
 Qiang Huang <h.huangqiang@huawei.com>
 Qinglan Peng <qinglanpeng@zju.edu.cn>
+QQ喵 <gqqnb2005@gmail.com>
 qudongfang <qudongfang@gmail.com>
 Raghavendra K T <raghavendra.kt@linux.vnet.ibm.com>
 Rahul Kadyan <hi@znck.me>
@@ -687,6 +690,7 @@ Rick Wieman <git@rickw.nl>
 Ritesh H Shukla <sritesh@vmware.com>
 Riyaz Faizullabhoy <riyaz.faizullabhoy@docker.com>
 Rob Gulewich <rgulewich@netflix.com>
+Rob Murray <rob.murray@docker.com>
 Robert Wallis <smilingrob@gmail.com>
 Robin Naundorf <r.naundorf@fh-muenster.de>
 Robin Speekenbrink <robin@kingsquare.nl>

Dockerfile

@@ -1,15 +1,15 @@
 # syntax=docker/dockerfile:1
 
 ARG BASE_VARIANT=alpine
-ARG ALPINE_VERSION=3.18
+ARG ALPINE_VERSION=3.20
 ARG BASE_DEBIAN_DISTRO=bookworm
 
-ARG GO_VERSION=1.21.5
+ARG GO_VERSION=1.22.8
 ARG XX_VERSION=1.2.1
 ARG GOVERSIONINFO_VERSION=v1.3.0
 ARG GOTESTSUM_VERSION=v1.10.0
-ARG BUILDX_VERSION=0.12.0
-ARG COMPOSE_VERSION=v2.22.0
+ARG BUILDX_VERSION=0.12.1
+ARG COMPOSE_VERSION=v2.24.3
 
 FROM --platform=$BUILDPLATFORM tonistiigi/xx:${XX_VERSION} AS xx
 
@@ -123,5 +123,8 @@ COPY --link . .
 FROM scratch AS plugins
 COPY --from=build-plugins /out .
 
+FROM scratch AS bin-image
+COPY --from=build /out/docker /docker
+
 FROM scratch AS binary
 COPY --from=build /out .

cli-plugins/examples/helloworld/main.go

@@ -45,8 +45,8 @@ func main() {
 		}
 
 		var (
-			who, context  string
-			preRun, debug bool
+			who, optContext string
+			preRun, debug   bool
 		)
 		cmd := &cobra.Command{
 			Use:   "helloworld",
@@ -65,7 +65,7 @@ func main() {
 					fmt.Fprintf(dockerCli.Err(), "Plugin debug mode enabled")
 				}
 
-				switch context {
+				switch optContext {
 				case "Christmas":
 					fmt.Fprintf(dockerCli.Out(), "Merry Christmas!\n")
 					return nil
@@ -92,7 +92,7 @@ func main() {
 		// These are intended to deliberately clash with the CLIs own top
 		// level arguments.
 		flags.BoolVarP(&debug, "debug", "D", false, "Enable debug")
-		flags.StringVarP(&context, "context", "c", "", "Is it Christmas?")
+		flags.StringVarP(&optContext, "context", "c", "", "Is it Christmas?")
 
 		cmd.AddCommand(goodbye, apiversion, exitStatus2)
 		return cmd

cli-plugins/manager/error.go

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

cli-plugins/manager/manager.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/cli/cli/config"
+	"github.com/docker/cli/cli/config/configfile"
 	"github.com/fvbommel/sortorder"
 	"github.com/spf13/cobra"
 	"golang.org/x/sync/errgroup"
@@ -42,10 +43,10 @@ func IsNotFound(err error) bool {
 	return ok
 }
 
-func getPluginDirs(dockerCli command.Cli) ([]string, error) {
+func getPluginDirs(cfg *configfile.ConfigFile) ([]string, error) {
 	var pluginDirs []string
 
-	if cfg := dockerCli.ConfigFile(); cfg != nil {
+	if cfg != nil {
 		pluginDirs = append(pluginDirs, cfg.CLIPluginsExtraDirs...)
 	}
 	pluginDir, err := config.Path("cli-plugins")
@@ -108,7 +109,7 @@ func listPluginCandidates(dirs []string) (map[string][]string, error) {
 
 // GetPlugin returns a plugin on the system by its name
 func GetPlugin(name string, dockerCli command.Cli, rootcmd *cobra.Command) (*Plugin, error) {
-	pluginDirs, err := getPluginDirs(dockerCli)
+	pluginDirs, err := getPluginDirs(dockerCli.ConfigFile())
 	if err != nil {
 		return nil, err
 	}
@@ -138,7 +139,7 @@ func GetPlugin(name string, dockerCli command.Cli, rootcmd *cobra.Command) (*Plu
 
 // ListPlugins produces a list of the plugins available on the system
 func ListPlugins(dockerCli command.Cli, rootcmd *cobra.Command) ([]Plugin, error) {
-	pluginDirs, err := getPluginDirs(dockerCli)
+	pluginDirs, err := getPluginDirs(dockerCli.ConfigFile())
 	if err != nil {
 		return nil, err
 	}
@@ -198,7 +199,7 @@ func PluginRunCommand(dockerCli command.Cli, name string, rootcmd *cobra.Command
 		return nil, errPluginNotFound(name)
 	}
 	exename := addExeSuffix(NamePrefix + name)
-	pluginDirs, err := getPluginDirs(dockerCli)
+	pluginDirs, err := getPluginDirs(dockerCli.ConfigFile())
 	if err != nil {
 		return nil, err
 	}

cli-plugins/manager/manager_test.go

@@ -149,7 +149,7 @@ func TestGetPluginDirs(t *testing.T) {
 	expected := append([]string{pluginDir}, defaultSystemPluginDirs...)
 
 	var pluginDirs []string
-	pluginDirs, err = getPluginDirs(cli)
+	pluginDirs, err = getPluginDirs(cli.ConfigFile())
 	assert.Equal(t, strings.Join(expected, ":"), strings.Join(pluginDirs, ":"))
 	assert.NilError(t, err)
 
@@ -160,7 +160,7 @@ func TestGetPluginDirs(t *testing.T) {
 	cli.SetConfigFile(&configfile.ConfigFile{
 		CLIPluginsExtraDirs: extras,
 	})
-	pluginDirs, err = getPluginDirs(cli)
+	pluginDirs, err = getPluginDirs(cli.ConfigFile())
 	assert.DeepEqual(t, expected, pluginDirs)
 	assert.NilError(t, err)
 }

cli-plugins/plugin/plugin.go

@@ -3,26 +3,19 @@ package plugin
 import (
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
-	"io"
-	"net"
 	"os"
 	"sync"
 
 	"github.com/docker/cli/cli"
 	"github.com/docker/cli/cli-plugins/manager"
+	"github.com/docker/cli/cli-plugins/socket"
 	"github.com/docker/cli/cli/command"
 	"github.com/docker/cli/cli/connhelper"
 	"github.com/docker/docker/client"
 	"github.com/spf13/cobra"
 )
 
-// CLIPluginSocketEnvKey is used to pass the plugin being
-// executed the abstract socket name it should listen on to know
-// when the CLI has exited.
-const CLIPluginSocketEnvKey = "DOCKER_CLI_PLUGIN_SOCKET"
-
 // PersistentPreRunE must be called by any plugin command (or
 // subcommand) which uses the cobra `PersistentPreRun*` hook. Plugins
 // which do not make use of `PersistentPreRun*` do not need to call
@@ -33,38 +26,6 @@ const CLIPluginSocketEnvKey = "DOCKER_CLI_PLUGIN_SOCKET"
 // called.
 var PersistentPreRunE func(*cobra.Command, []string) error
 
-// closeOnCLISocketClose connects to the socket specified
-// by the DOCKER_CLI_PLUGIN_SOCKET env var, if present, and attempts
-// to read from it until it receives an EOF, which signals that
-// the CLI is going to exit and the plugin should also exit.
-func closeOnCLISocketClose(cancel func()) {
-	socketAddr, ok := os.LookupEnv(CLIPluginSocketEnvKey)
-	if !ok {
-		// if a plugin compiled against a more recent version of docker/cli
-		// is executed by an older CLI binary, ignore missing environment
-		// variable and behave as usual
-		return
-	}
-	addr, err := net.ResolveUnixAddr("unix", socketAddr)
-	if err != nil {
-		return
-	}
-	cliCloseConn, err := net.DialUnix("unix", nil, addr)
-	if err != nil {
-		return
-	}
-
-	go func() {
-		b := make([]byte, 1)
-		for {
-			_, err := cliCloseConn.Read(b)
-			if errors.Is(err, io.EOF) {
-				cancel()
-			}
-		}
-	}()
-}
-
 // RunPlugin executes the specified plugin command
 func RunPlugin(dockerCli *command.DockerCli, plugin *cobra.Command, meta manager.Metadata) error {
 	tcmd := newPluginCommand(dockerCli, plugin, meta)
@@ -81,9 +42,10 @@ func RunPlugin(dockerCli *command.DockerCli, plugin *cobra.Command, meta manager
 			}
 			ctx, cancel := context.WithCancel(cmdContext)
 			cmd.SetContext(ctx)
-			closeOnCLISocketClose(cancel)
+			// Set up the context to cancel based on signalling via CLI socket.
+			socket.ConnectAndWait(cancel)
 
-			var opts []command.InitializeOpt
+			var opts []command.CLIOption
 			if os.Getenv("DOCKER_CLI_PLUGIN_USE_DIAL_STDIO") != "" {
 				opts = append(opts, withPluginClientConn(plugin.Name()))
 			}
@@ -129,7 +91,7 @@ func Run(makeCmd func(command.Cli) *cobra.Command, meta manager.Metadata) {
 	}
 }
 
-func withPluginClientConn(name string) command.InitializeOpt {
+func withPluginClientConn(name string) command.CLIOption {
 	return command.WithInitializeClient(func(dockerCli *command.DockerCli) (client.APIClient, error) {
 		cmd := "docker"
 		if x := os.Getenv(manager.ReexecEnvvar); x != "" {

cli-plugins/socket/socket.go

@@ -0,0 +1,72 @@
+package socket
+
+import (
+	"errors"
+	"io"
+	"net"
+	"os"
+
+	"github.com/docker/distribution/uuid"
+)
+
+// EnvKey represents the well-known environment variable used to pass the plugin being
+// executed the socket name it should listen on to coordinate with the host CLI.
+const EnvKey = "DOCKER_CLI_PLUGIN_SOCKET"
+
+// SetupConn sets up a Unix socket listener, establishes a goroutine to handle connections
+// and update the conn pointer, and returns the listener for the socket (which the caller
+// is responsible for closing when it's no longer needed).
+func SetupConn(conn **net.UnixConn) (*net.UnixListener, error) {
+	listener, err := listen("docker_cli_" + uuid.Generate().String())
+	if err != nil {
+		return nil, err
+	}
+
+	accept(listener, conn)
+
+	return listener, nil
+}
+
+func accept(listener *net.UnixListener, conn **net.UnixConn) {
+	go func() {
+		for {
+			// ignore error here, if we failed to accept a connection,
+			// conn is nil and we fallback to previous behavior
+			*conn, _ = listener.AcceptUnix()
+			// perform any platform-specific actions on accept (e.g. unlink non-abstract sockets)
+			onAccept(*conn, listener)
+		}
+	}()
+}
+
+// ConnectAndWait connects to the socket passed via well-known env var,
+// if present, and attempts to read from it until it receives an EOF, at which
+// point cb is called.
+func ConnectAndWait(cb func()) {
+	socketAddr, ok := os.LookupEnv(EnvKey)
+	if !ok {
+		// if a plugin compiled against a more recent version of docker/cli
+		// is executed by an older CLI binary, ignore missing environment
+		// variable and behave as usual
+		return
+	}
+	addr, err := net.ResolveUnixAddr("unix", socketAddr)
+	if err != nil {
+		return
+	}
+	conn, err := net.DialUnix("unix", nil, addr)
+	if err != nil {
+		return
+	}
+
+	go func() {
+		b := make([]byte, 1)
+		for {
+			_, err := conn.Read(b)
+			if errors.Is(err, io.EOF) {
+				cb()
+				return
+			}
+		}
+	}()
+}

cli-plugins/socket/socket_darwin.go

@@ -0,0 +1,19 @@
+package socket
+
+import (
+	"net"
+	"os"
+	"path/filepath"
+	"syscall"
+)
+
+func listen(socketname string) (*net.UnixListener, error) {
+	return net.ListenUnix("unix", &net.UnixAddr{
+		Name: filepath.Join(os.TempDir(), socketname),
+		Net:  "unix",
+	})
+}
+
+func onAccept(conn *net.UnixConn, listener *net.UnixListener) {
+	syscall.Unlink(listener.Addr().String())
+}

cli-plugins/socket/socket_nodarwin.go

@@ -0,0 +1,20 @@
+//go:build !darwin && !openbsd
+
+package socket
+
+import (
+	"net"
+)
+
+func listen(socketname string) (*net.UnixListener, error) {
+	return net.ListenUnix("unix", &net.UnixAddr{
+		Name: "@" + socketname,
+		Net:  "unix",
+	})
+}
+
+func onAccept(conn *net.UnixConn, listener *net.UnixListener) {
+	// do nothing
+	// while on darwin and OpenBSD we would unlink here;
+	// on non-darwin the socket is abstract and not present on the filesystem
+}

cli-plugins/socket/socket_openbsd.go

@@ -0,0 +1,19 @@
+package socket
+
+import (
+	"net"
+	"os"
+	"path/filepath"
+	"syscall"
+)
+
+func listen(socketname string) (*net.UnixListener, error) {
+	return net.ListenUnix("unix", &net.UnixAddr{
+		Name: filepath.Join(os.TempDir(), socketname),
+		Net:  "unix",
+	})
+}
+
+func onAccept(conn *net.UnixConn, listener *net.UnixListener) {
+	syscall.Unlink(listener.Addr().String())
+}

cli-plugins/socket/socket_test.go

@@ -0,0 +1,133 @@
+package socket
+
+import (
+	"io/fs"
+	"net"
+	"os"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+
+	"gotest.tools/v3/assert"
+	"gotest.tools/v3/poll"
+)
+
+func TestSetupConn(t *testing.T) {
+	t.Run("updates conn when connected", func(t *testing.T) {
+		var conn *net.UnixConn
+		listener, err := SetupConn(&conn)
+		assert.NilError(t, err)
+		assert.Check(t, listener != nil, "returned nil listener but no error")
+		addr, err := net.ResolveUnixAddr("unix", listener.Addr().String())
+		assert.NilError(t, err, "failed to resolve listener address")
+
+		_, err = net.DialUnix("unix", nil, addr)
+		assert.NilError(t, err, "failed to dial returned listener")
+
+		pollConnNotNil(t, &conn)
+	})
+
+	t.Run("allows reconnects", func(t *testing.T) {
+		var conn *net.UnixConn
+		listener, err := SetupConn(&conn)
+		assert.NilError(t, err)
+		assert.Check(t, listener != nil, "returned nil listener but no error")
+		addr, err := net.ResolveUnixAddr("unix", listener.Addr().String())
+		assert.NilError(t, err, "failed to resolve listener address")
+
+		otherConn, err := net.DialUnix("unix", nil, addr)
+		assert.NilError(t, err, "failed to dial returned listener")
+
+		otherConn.Close()
+
+		_, err = net.DialUnix("unix", nil, addr)
+		assert.NilError(t, err, "failed to redial listener")
+	})
+
+	t.Run("does not leak sockets to local directory", func(t *testing.T) {
+		var conn *net.UnixConn
+		listener, err := SetupConn(&conn)
+		assert.NilError(t, err)
+		assert.Check(t, listener != nil, "returned nil listener but no error")
+		checkDirNoPluginSocket(t)
+
+		addr, err := net.ResolveUnixAddr("unix", listener.Addr().String())
+		assert.NilError(t, err, "failed to resolve listener address")
+		_, err = net.DialUnix("unix", nil, addr)
+		assert.NilError(t, err, "failed to dial returned listener")
+		checkDirNoPluginSocket(t)
+	})
+}
+
+func checkDirNoPluginSocket(t *testing.T) {
+	t.Helper()
+
+	files, err := os.ReadDir(".")
+	assert.NilError(t, err, "failed to list files in dir to check for leaked sockets")
+
+	for _, f := range files {
+		info, err := f.Info()
+		assert.NilError(t, err, "failed to check file info")
+		// check for a socket with `docker_cli_` in the name (from `SetupConn()`)
+		if strings.Contains(f.Name(), "docker_cli_") && info.Mode().Type() == fs.ModeSocket {
+			t.Fatal("found socket in a local directory")
+		}
+	}
+}
+
+func TestConnectAndWait(t *testing.T) {
+	t.Run("calls cancel func on EOF", func(t *testing.T) {
+		var conn *net.UnixConn
+		listener, err := SetupConn(&conn)
+		assert.NilError(t, err, "failed to setup listener")
+
+		done := make(chan struct{})
+		t.Setenv(EnvKey, listener.Addr().String())
+		cancelFunc := func() {
+			done <- struct{}{}
+		}
+		ConnectAndWait(cancelFunc)
+		pollConnNotNil(t, &conn)
+		conn.Close()
+
+		select {
+		case <-done:
+		case <-time.After(10 * time.Millisecond):
+			t.Fatal("cancel function not closed after 10ms")
+		}
+	})
+
+	// TODO: this test cannot be executed with `t.Parallel()`, due to
+	// relying on goroutine numbers to ensure correct behaviour
+	t.Run("connect goroutine exits after EOF", func(t *testing.T) {
+		var conn *net.UnixConn
+		listener, err := SetupConn(&conn)
+		assert.NilError(t, err, "failed to setup listener")
+		t.Setenv(EnvKey, listener.Addr().String())
+		numGoroutines := runtime.NumGoroutine()
+
+		ConnectAndWait(func() {})
+		assert.Equal(t, runtime.NumGoroutine(), numGoroutines+1)
+
+		pollConnNotNil(t, &conn)
+		conn.Close()
+		poll.WaitOn(t, func(t poll.LogT) poll.Result {
+			if runtime.NumGoroutine() > numGoroutines+1 {
+				return poll.Continue("waiting for connect goroutine to exit")
+			}
+			return poll.Success()
+		}, poll.WithDelay(1*time.Millisecond), poll.WithTimeout(10*time.Millisecond))
+	})
+}
+
+func pollConnNotNil(t *testing.T, conn **net.UnixConn) {
+	t.Helper()
+
+	poll.WaitOn(t, func(t poll.LogT) poll.Result {
+		if *conn == nil {
+			return poll.Continue("waiting for conn to not be nil")
+		}
+		return poll.Success()
+	}, poll.WithDelay(1*time.Millisecond), poll.WithTimeout(10*time.Millisecond))
+}

cli/cobra.go

@@ -176,7 +176,7 @@ func (tcmd *TopLevelCommand) HandleGlobalFlags() (*cobra.Command, []string, erro
 }
 
 // Initialize finalises global option parsing and initializes the docker client.
-func (tcmd *TopLevelCommand) Initialize(ops ...command.InitializeOpt) error {
+func (tcmd *TopLevelCommand) Initialize(ops ...command.CLIOption) error {
 	tcmd.opts.SetDefaultOptions(tcmd.flags)
 	return tcmd.dockerCli.Initialize(tcmd.opts, ops...)
 }

cli/command/builder/prune.go

@@ -30,7 +30,7 @@ func NewPruneCommand(dockerCli command.Cli) *cobra.Command {
 		Short: "Remove build cache",
 		Args:  cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			spaceReclaimed, output, err := runPrune(dockerCli, options)
+			spaceReclaimed, output, err := runPrune(cmd.Context(), dockerCli, options)
 			if err != nil {
 				return err
 			}
@@ -58,7 +58,7 @@ const (
 	allCacheWarning = `WARNING! This will remove all build cache. Are you sure you want to continue?`
 )
 
-func runPrune(dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint64, output string, err error) {
+func runPrune(ctx context.Context, dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint64, output string, err error) {
 	pruneFilters := options.filter.Value()
 	pruneFilters = command.PruneFilters(dockerCli, pruneFilters)
 
@@ -70,7 +70,7 @@ func runPrune(dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint6
 		return 0, "", nil
 	}
 
-	report, err := dockerCli.Client().BuildCachePrune(context.Background(), types.BuildCachePruneOptions{
+	report, err := dockerCli.Client().BuildCachePrune(ctx, types.BuildCachePruneOptions{
 		All:         options.all,
 		KeepStorage: options.keepStorage.Value(),
 		Filters:     pruneFilters,
@@ -93,6 +93,6 @@ func runPrune(dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint6
 }
 
 // CachePrune executes a prune command for build cache
-func CachePrune(dockerCli command.Cli, all bool, filter opts.FilterOpt) (uint64, string, error) {
-	return runPrune(dockerCli, pruneOptions{force: true, all: all, filter: filter})
+func CachePrune(ctx context.Context, dockerCli command.Cli, all bool, filter opts.FilterOpt) (uint64, string, error) {
+	return runPrune(ctx, dockerCli, pruneOptions{force: true, all: all, filter: filter})
 }

cli/command/checkpoint/create.go

@@ -28,7 +28,7 @@ func newCreateCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.container = args[0]
 			opts.checkpoint = args[1]
-			return runCreate(dockerCli, opts)
+			return runCreate(cmd.Context(), dockerCli, opts)
 		},
 		ValidArgsFunction: completion.NoComplete,
 	}
@@ -40,8 +40,8 @@ func newCreateCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runCreate(dockerCli command.Cli, opts createOptions) error {
-	err := dockerCli.Client().CheckpointCreate(context.Background(), opts.container, checkpoint.CreateOptions{
+func runCreate(ctx context.Context, dockerCli command.Cli, opts createOptions) error {
+	err := dockerCli.Client().CheckpointCreate(ctx, opts.container, checkpoint.CreateOptions{
 		CheckpointID:  opts.checkpoint,
 		CheckpointDir: opts.checkpointDir,
 		Exit:          !opts.leaveRunning,

cli/command/checkpoint/list.go

@@ -24,7 +24,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command {
 		Short:   "List checkpoints for a container",
 		Args:    cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runList(dockerCli, args[0], opts)
+			return runList(cmd.Context(), dockerCli, args[0], opts)
 		},
 		ValidArgsFunction: completion.ContainerNames(dockerCli, false),
 	}
@@ -35,8 +35,8 @@ func newListCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runList(dockerCli command.Cli, container string, opts listOptions) error {
-	checkpoints, err := dockerCli.Client().CheckpointList(context.Background(), container, checkpoint.ListOptions{
+func runList(ctx context.Context, dockerCli command.Cli, container string, opts listOptions) error {
+	checkpoints, err := dockerCli.Client().CheckpointList(ctx, container, checkpoint.ListOptions{
 		CheckpointDir: opts.checkpointDir,
 	})
 	if err != nil {

cli/command/checkpoint/remove.go

@@ -22,7 +22,7 @@ func newRemoveCommand(dockerCli command.Cli) *cobra.Command {
 		Short:   "Remove a checkpoint",
 		Args:    cli.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runRemove(dockerCli, args[0], args[1], opts)
+			return runRemove(cmd.Context(), dockerCli, args[0], args[1], opts)
 		},
 	}
 
@@ -32,8 +32,8 @@ func newRemoveCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runRemove(dockerCli command.Cli, container string, checkpointID string, opts removeOptions) error {
-	return dockerCli.Client().CheckpointDelete(context.Background(), container, checkpoint.DeleteOptions{
+func runRemove(ctx context.Context, dockerCli command.Cli, container string, checkpointID string, opts removeOptions) error {
+	return dockerCli.Client().CheckpointDelete(ctx, container, checkpoint.DeleteOptions{
 		CheckpointID:  checkpointID,
 		CheckpointDir: opts.checkpointDir,
 	})

cli/command/cli.go

@@ -1,3 +1,6 @@
+// FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
+//go:build go1.19
+
 package command
 
 import (
@@ -49,7 +52,7 @@ type Cli interface {
 	Client() client.APIClient
 	Streams
 	SetIn(in *streams.In)
-	Apply(ops ...DockerCliOption) error
+	Apply(ops ...CLIOption) error
 	ConfigFile() *configfile.ConfigFile
 	ServerInfo() ServerInfo
 	NotaryClient(imgRefAndAuth trust.ImageRefAndAuth, actions []string) (notaryclient.Repository, error)
@@ -82,6 +85,11 @@ type DockerCli struct {
 	dockerEndpoint     docker.Endpoint
 	contextStoreConfig store.Config
 	initTimeout        time.Duration
+
+	// baseCtx is the base context used for internal operations. In the future
+	// this may be replaced by explicitly passing a context to functions that
+	// need it.
+	baseCtx context.Context
 }
 
 // DefaultVersion returns api.defaultVersion.
@@ -194,11 +202,8 @@ func (cli *DockerCli) RegistryClient(allowInsecure bool) registryclient.Registry
 	return registryclient.NewRegistryClient(resolver, UserAgent(), allowInsecure)
 }
 
-// InitializeOpt is the type of the functional options passed to DockerCli.Initialize
-type InitializeOpt func(dockerCli *DockerCli) error
-
 // WithInitializeClient is passed to DockerCli.Initialize by callers who wish to set a particular API Client for use by the CLI.
-func WithInitializeClient(makeClient func(dockerCli *DockerCli) (client.APIClient, error)) InitializeOpt {
+func WithInitializeClient(makeClient func(dockerCli *DockerCli) (client.APIClient, error)) CLIOption {
 	return func(dockerCli *DockerCli) error {
 		var err error
 		dockerCli.client, err = makeClient(dockerCli)
@@ -208,7 +213,7 @@ func WithInitializeClient(makeClient func(dockerCli *DockerCli) (client.APIClien
 
 // Initialize the dockerCli runs initialization that must happen after command
 // line flags are parsed.
-func (cli *DockerCli) Initialize(opts *cliflags.ClientOptions, ops ...InitializeOpt) error {
+func (cli *DockerCli) Initialize(opts *cliflags.ClientOptions, ops ...CLIOption) error {
 	for _, o := range ops {
 		if err := o(cli); err != nil {
 			return err
@@ -323,8 +328,7 @@ func (cli *DockerCli) getInitTimeout() time.Duration {
 }
 
 func (cli *DockerCli) initializeFromClient() {
-	ctx := context.Background()
-	ctx, cancel := context.WithTimeout(ctx, cli.getInitTimeout())
+	ctx, cancel := context.WithTimeout(cli.baseCtx, cli.getInitTimeout())
 	defer cancel()
 
 	ping, err := cli.client.Ping(ctx)
@@ -444,13 +448,16 @@ func (cli *DockerCli) initialize() error {
 				return
 			}
 		}
+		if cli.baseCtx == nil {
+			cli.baseCtx = context.Background()
+		}
 		cli.initializeFromClient()
 	})
 	return cli.initErr
 }
 
 // Apply all the operation on the cli
-func (cli *DockerCli) Apply(ops ...DockerCliOption) error {
+func (cli *DockerCli) Apply(ops ...CLIOption) error {
 	for _, op := range ops {
 		if err := op(cli); err != nil {
 			return err
@@ -479,15 +486,15 @@ type ServerInfo struct {
 // NewDockerCli returns a DockerCli instance with all operators applied on it.
 // It applies by default the standard streams, and the content trust from
 // environment.
-func NewDockerCli(ops ...DockerCliOption) (*DockerCli, error) {
-	defaultOps := []DockerCliOption{
+func NewDockerCli(ops ...CLIOption) (*DockerCli, error) {
+	defaultOps := []CLIOption{
 		WithContentTrustFromEnv(),
 		WithDefaultContextStoreConfig(),
 		WithStandardStreams(),
 	}
 	ops = append(defaultOps, ops...)
 
-	cli := &DockerCli{}
+	cli := &DockerCli{baseCtx: context.Background()}
 	if err := cli.Apply(ops...); err != nil {
 		return nil, err
 	}

cli/command/cli_options.go

@@ -1,6 +1,7 @@
 package command
 
 import (
+	"context"
 	"io"
 	"os"
 	"strconv"
@@ -10,11 +11,21 @@ import (
 	"github.com/moby/term"
 )
 
+// CLIOption applies a modification on a DockerCli.
+type CLIOption func(cli *DockerCli) error
+
 // DockerCliOption applies a modification on a DockerCli.
-type DockerCliOption func(cli *DockerCli) error
+//
+// Deprecated: use [CLIOption] instead.
+type DockerCliOption = CLIOption
+
+// InitializeOpt is the type of the functional options passed to DockerCli.Initialize
+//
+// Deprecated: use [CLIOption] instead.
+type InitializeOpt = CLIOption
 
 // WithStandardStreams sets a cli in, out and err streams with the standard streams.
-func WithStandardStreams() DockerCliOption {
+func WithStandardStreams() CLIOption {
 	return func(cli *DockerCli) error {
 		// Set terminal emulation based on platform as required.
 		stdin, stdout, stderr := term.StdStreams()
@@ -25,8 +36,17 @@ func WithStandardStreams() DockerCliOption {
 	}
 }
 
+// WithBaseContext sets the base context of a cli. It is used to propagate
+// the context from the command line to the client.
+func WithBaseContext(ctx context.Context) CLIOption {
+	return func(cli *DockerCli) error {
+		cli.baseCtx = ctx
+		return nil
+	}
+}
+
 // WithCombinedStreams uses the same stream for the output and error streams.
-func WithCombinedStreams(combined io.Writer) DockerCliOption {
+func WithCombinedStreams(combined io.Writer) CLIOption {
 	return func(cli *DockerCli) error {
 		cli.out = streams.NewOut(combined)
 		cli.err = combined
@@ -35,7 +55,7 @@ func WithCombinedStreams(combined io.Writer) DockerCliOption {
 }
 
 // WithInputStream sets a cli input stream.
-func WithInputStream(in io.ReadCloser) DockerCliOption {
+func WithInputStream(in io.ReadCloser) CLIOption {
 	return func(cli *DockerCli) error {
 		cli.in = streams.NewIn(in)
 		return nil
@@ -43,7 +63,7 @@ func WithInputStream(in io.ReadCloser) DockerCliOption {
 }
 
 // WithOutputStream sets a cli output stream.
-func WithOutputStream(out io.Writer) DockerCliOption {
+func WithOutputStream(out io.Writer) CLIOption {
 	return func(cli *DockerCli) error {
 		cli.out = streams.NewOut(out)
 		return nil
@@ -51,7 +71,7 @@ func WithOutputStream(out io.Writer) DockerCliOption {
 }
 
 // WithErrorStream sets a cli error stream.
-func WithErrorStream(err io.Writer) DockerCliOption {
+func WithErrorStream(err io.Writer) CLIOption {
 	return func(cli *DockerCli) error {
 		cli.err = err
 		return nil
@@ -59,7 +79,7 @@ func WithErrorStream(err io.Writer) DockerCliOption {
 }
 
 // WithContentTrustFromEnv enables content trust on a cli from environment variable DOCKER_CONTENT_TRUST value.
-func WithContentTrustFromEnv() DockerCliOption {
+func WithContentTrustFromEnv() CLIOption {
 	return func(cli *DockerCli) error {
 		cli.contentTrust = false
 		if e := os.Getenv("DOCKER_CONTENT_TRUST"); e != "" {
@@ -73,7 +93,7 @@ func WithContentTrustFromEnv() DockerCliOption {
 }
 
 // WithContentTrust enables content trust on a cli.
-func WithContentTrust(enabled bool) DockerCliOption {
+func WithContentTrust(enabled bool) CLIOption {
 	return func(cli *DockerCli) error {
 		cli.contentTrust = enabled
 		return nil
@@ -81,7 +101,7 @@ func WithContentTrust(enabled bool) DockerCliOption {
 }
 
 // WithDefaultContextStoreConfig configures the cli to use the default context store configuration.
-func WithDefaultContextStoreConfig() DockerCliOption {
+func WithDefaultContextStoreConfig() CLIOption {
 	return func(cli *DockerCli) error {
 		cli.contextStoreConfig = DefaultContextStoreConfig()
 		return nil
@@ -89,7 +109,7 @@ func WithDefaultContextStoreConfig() DockerCliOption {
 }
 
 // WithAPIClient configures the cli to use the given API client.
-func WithAPIClient(c client.APIClient) DockerCliOption {
+func WithAPIClient(c client.APIClient) CLIOption {
 	return func(cli *DockerCli) error {
 		cli.client = c
 		return nil

cli/command/config/create.go

@@ -35,7 +35,7 @@ func newConfigCreateCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			createOpts.Name = args[0]
 			createOpts.File = args[1]
-			return RunConfigCreate(dockerCli, createOpts)
+			return RunConfigCreate(cmd.Context(), dockerCli, createOpts)
 		},
 		ValidArgsFunction: completion.NoComplete,
 	}
@@ -48,9 +48,8 @@ func newConfigCreateCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunConfigCreate creates a config with the given options.
-func RunConfigCreate(dockerCli command.Cli, options CreateOptions) error {
+func RunConfigCreate(ctx context.Context, dockerCli command.Cli, options CreateOptions) error {
 	client := dockerCli.Client()
-	ctx := context.Background()
 
 	var in io.Reader = dockerCli.In()
 	if options.File != "-" {

cli/command/config/inspect.go

@@ -1,3 +1,6 @@
+// FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
+//go:build go1.19
+
 package config
 
 import (
@@ -27,7 +30,7 @@ func newConfigInspectCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Names = args
-			return RunConfigInspect(dockerCli, opts)
+			return RunConfigInspect(cmd.Context(), dockerCli, opts)
 		},
 		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 			return completeNames(dockerCli)(cmd, args, toComplete)
@@ -40,9 +43,8 @@ func newConfigInspectCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunConfigInspect inspects the given Swarm config.
-func RunConfigInspect(dockerCli command.Cli, opts InspectOptions) error {
+func RunConfigInspect(ctx context.Context, dockerCli command.Cli, opts InspectOptions) error {
 	client := dockerCli.Client()
-	ctx := context.Background()
 
 	if opts.Pretty {
 		opts.Format = "pretty"

cli/command/config/ls.go

@@ -31,7 +31,7 @@ func newConfigListCommand(dockerCli command.Cli) *cobra.Command {
 		Short:   "List configs",
 		Args:    cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return RunConfigList(dockerCli, listOpts)
+			return RunConfigList(cmd.Context(), dockerCli, listOpts)
 		},
 		ValidArgsFunction: completion.NoComplete,
 	}
@@ -45,9 +45,8 @@ func newConfigListCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunConfigList lists Swarm configs.
-func RunConfigList(dockerCli command.Cli, options ListOptions) error {
+func RunConfigList(ctx context.Context, dockerCli command.Cli, options ListOptions) error {
 	client := dockerCli.Client()
-	ctx := context.Background()
 
 	configs, err := client.ConfigList(ctx, types.ConfigListOptions{Filters: options.Filter.Value()})
 	if err != nil {

cli/command/config/remove.go

@@ -26,7 +26,7 @@ func newConfigRemoveCommand(dockerCli command.Cli) *cobra.Command {
 			opts := RemoveOptions{
 				Names: args,
 			}
-			return RunConfigRemove(dockerCli, opts)
+			return RunConfigRemove(cmd.Context(), dockerCli, opts)
 		},
 		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 			return completeNames(dockerCli)(cmd, args, toComplete)
@@ -35,9 +35,8 @@ func newConfigRemoveCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunConfigRemove removes the given Swarm configs.
-func RunConfigRemove(dockerCli command.Cli, opts RemoveOptions) error {
+func RunConfigRemove(ctx context.Context, dockerCli command.Cli, opts RemoveOptions) error {
 	client := dockerCli.Client()
-	ctx := context.Background()
 
 	var errs []string
 

cli/command/container/attach.go

@@ -53,7 +53,7 @@ func NewAttachCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctr = args[0]
-			return RunAttach(context.Background(), dockerCli, ctr, &opts)
+			return RunAttach(cmd.Context(), dockerCli, ctr, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container attach, docker attach",

cli/command/container/commit.go

@@ -35,7 +35,7 @@ func NewCommitCommand(dockerCli command.Cli) *cobra.Command {
 			if len(args) > 1 {
 				options.reference = args[1]
 			}
-			return runCommit(dockerCli, &options)
+			return runCommit(cmd.Context(), dockerCli, &options)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container commit, docker commit",
@@ -56,9 +56,7 @@ func NewCommitCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runCommit(dockerCli command.Cli, options *commitOptions) error {
-	ctx := context.Background()
-
+func runCommit(ctx context.Context, dockerCli command.Cli, options *commitOptions) error {
 	response, err := dockerCli.Client().ContainerCommit(ctx, options.container, container.CommitOptions{
 		Reference: options.reference,
 		Comment:   options.comment,

cli/command/container/cp.go

@@ -151,7 +151,7 @@ func NewCopyCommand(dockerCli command.Cli) *cobra.Command {
 				// User did not specify "quiet" flag; suppress output if no terminal is attached
 				opts.quiet = !dockerCli.Out().IsTerminal()
 			}
-			return runCopy(dockerCli, opts)
+			return runCopy(cmd.Context(), dockerCli, opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container cp, docker cp",
@@ -169,7 +169,7 @@ func progressHumanSize(n int64) string {
 	return units.HumanSizeWithPrecision(float64(n), 3)
 }
 
-func runCopy(dockerCli command.Cli, opts copyOptions) error {
+func runCopy(ctx context.Context, dockerCli command.Cli, opts copyOptions) error {
 	srcContainer, srcPath := splitCpArg(opts.source)
 	destContainer, destPath := splitCpArg(opts.destination)
 
@@ -191,8 +191,6 @@ func runCopy(dockerCli command.Cli, opts copyOptions) error {
 		copyConfig.container = destContainer
 	}
 
-	ctx := context.Background()
-
 	switch direction {
 	case fromContainer:
 		return copyFromContainer(ctx, dockerCli, copyConfig)

cli/command/container/cp_test.go

@@ -1,6 +1,7 @@
 package container
 
 import (
+	"context"
 	"io"
 	"os"
 	"runtime"
@@ -41,7 +42,7 @@ func TestRunCopyWithInvalidArguments(t *testing.T) {
 	}
 	for _, testcase := range testcases {
 		t.Run(testcase.doc, func(t *testing.T) {
-			err := runCopy(test.NewFakeCli(nil), testcase.options)
+			err := runCopy(context.TODO(), test.NewFakeCli(nil), testcase.options)
 			assert.Error(t, err, testcase.expectedErr)
 		})
 	}
@@ -58,7 +59,7 @@ func TestRunCopyFromContainerToStdout(t *testing.T) {
 	}
 	options := copyOptions{source: "container:/path", destination: "-"}
 	cli := test.NewFakeCli(fakeClient)
-	err := runCopy(cli, options)
+	err := runCopy(context.TODO(), cli, options)
 	assert.NilError(t, err)
 	assert.Check(t, is.Equal(tarContent, cli.OutBuffer().String()))
 	assert.Check(t, is.Equal("", cli.ErrBuffer().String()))
@@ -78,7 +79,7 @@ func TestRunCopyFromContainerToFilesystem(t *testing.T) {
 	}
 	options := copyOptions{source: "container:/path", destination: destDir.Path(), quiet: true}
 	cli := test.NewFakeCli(fakeClient)
-	err := runCopy(cli, options)
+	err := runCopy(context.TODO(), cli, options)
 	assert.NilError(t, err)
 	assert.Check(t, is.Equal("", cli.OutBuffer().String()))
 	assert.Check(t, is.Equal("", cli.ErrBuffer().String()))
@@ -106,7 +107,7 @@ func TestRunCopyFromContainerToFilesystemMissingDestinationDirectory(t *testing.
 		destination: destDir.Join("missing", "foo"),
 	}
 	cli := test.NewFakeCli(fakeClient)
-	err := runCopy(cli, options)
+	err := runCopy(context.TODO(), cli, options)
 	assert.ErrorContains(t, err, destDir.Join("missing"))
 }
 
@@ -119,7 +120,7 @@ func TestRunCopyToContainerFromFileWithTrailingSlash(t *testing.T) {
 		destination: "container:/path",
 	}
 	cli := test.NewFakeCli(&fakeClient{})
-	err := runCopy(cli, options)
+	err := runCopy(context.TODO(), cli, options)
 
 	expectedError := "not a directory"
 	if runtime.GOOS == "windows" {
@@ -134,7 +135,7 @@ func TestRunCopyToContainerSourceDoesNotExist(t *testing.T) {
 		destination: "container:/path",
 	}
 	cli := test.NewFakeCli(&fakeClient{})
-	err := runCopy(cli, options)
+	err := runCopy(context.TODO(), cli, options)
 	expected := "no such file or directory"
 	if runtime.GOOS == "windows" {
 		expected = "cannot find the file specified"
@@ -193,7 +194,7 @@ func TestSplitCpArg(t *testing.T) {
 func TestRunCopyFromContainerToFilesystemIrregularDestination(t *testing.T) {
 	options := copyOptions{source: "container:/dev/null", destination: "/dev/random"}
 	cli := test.NewFakeCli(nil)
-	err := runCopy(cli, options)
+	err := runCopy(context.TODO(), cli, options)
 	assert.Assert(t, err != nil)
 	expected := `"/dev/random" must be a directory or a regular file`
 	assert.ErrorContains(t, err, expected)

cli/command/container/create.go

@@ -55,7 +55,7 @@ func NewCreateCommand(dockerCli command.Cli) *cobra.Command {
 			if len(args) > 1 {
 				copts.Args = args[1:]
 			}
-			return runCreate(dockerCli, cmd.Flags(), &options, copts)
+			return runCreate(cmd.Context(), dockerCli, cmd.Flags(), &options, copts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container create, docker create",
@@ -80,7 +80,7 @@ func NewCreateCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runCreate(dockerCli command.Cli, flags *pflag.FlagSet, options *createOptions, copts *containerOptions) error {
+func runCreate(ctx context.Context, dockerCli command.Cli, flags *pflag.FlagSet, options *createOptions, copts *containerOptions) error {
 	if err := validatePullOpt(options.pull); err != nil {
 		reportError(dockerCli.Err(), "create", err.Error(), true)
 		return cli.StatusError{StatusCode: 125}
@@ -104,7 +104,7 @@ func runCreate(dockerCli command.Cli, flags *pflag.FlagSet, options *createOptio
 		reportError(dockerCli.Err(), "create", err.Error(), true)
 		return cli.StatusError{StatusCode: 125}
 	}
-	id, err := createContainer(context.Background(), dockerCli, containerCfg, options)
+	id, err := createContainer(ctx, dockerCli, containerCfg, options)
 	if err != nil {
 		return err
 	}

cli/command/container/create_test.go

@@ -181,6 +181,7 @@ func TestCreateContainerImagePullPolicyInvalid(t *testing.T) {
 		t.Run(tc.PullPolicy, func(t *testing.T) {
 			dockerCli := test.NewFakeCli(&fakeClient{})
 			err := runCreate(
+				context.TODO(),
 				dockerCli,
 				&pflag.FlagSet{},
 				&createOptions{pull: tc.PullPolicy},

cli/command/container/diff.go

@@ -25,7 +25,7 @@ func NewDiffCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.container = args[0]
-			return runDiff(dockerCli, &opts)
+			return runDiff(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container diff, docker diff",
@@ -34,12 +34,10 @@ func NewDiffCommand(dockerCli command.Cli) *cobra.Command {
 	}
 }
 
-func runDiff(dockerCli command.Cli, opts *diffOptions) error {
+func runDiff(ctx context.Context, dockerCli command.Cli, opts *diffOptions) error {
 	if opts.container == "" {
 		return errors.New("Container name cannot be empty")
 	}
-	ctx := context.Background()
-
 	changes, err := dockerCli.Client().ContainerDiff(ctx, opts.container)
 	if err != nil {
 		return err

cli/command/container/exec.go

@@ -52,7 +52,7 @@ func NewExecCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			container = args[0]
 			options.Command = args[1:]
-			return RunExec(context.Background(), dockerCli, container, options)
+			return RunExec(cmd.Context(), dockerCli, container, options)
 		},
 		ValidArgsFunction: completion.ContainerNames(dockerCli, false, func(container types.Container) bool {
 			return container.State != "paused"

cli/command/container/exec_test.go

@@ -192,16 +192,16 @@ func TestRunExec(t *testing.T) {
 
 	for _, testcase := range testcases {
 		t.Run(testcase.doc, func(t *testing.T) {
-			cli := test.NewFakeCli(&testcase.client)
+			fakeCLI := test.NewFakeCli(&testcase.client)
 
-			err := RunExec(context.Background(), cli, "thecontainer", testcase.options)
+			err := RunExec(context.TODO(), fakeCLI, "thecontainer", testcase.options)
 			if testcase.expectedError != "" {
 				assert.ErrorContains(t, err, testcase.expectedError)
 			} else if !assert.Check(t, err) {
 				return
 			}
-			assert.Check(t, is.Equal(testcase.expectedOut, cli.OutBuffer().String()))
-			assert.Check(t, is.Equal(testcase.expectedErr, cli.ErrBuffer().String()))
+			assert.Check(t, is.Equal(testcase.expectedOut, fakeCLI.OutBuffer().String()))
+			assert.Check(t, is.Equal(testcase.expectedErr, fakeCLI.ErrBuffer().String()))
 		})
 	}
 }

cli/command/container/export.go

@@ -26,7 +26,7 @@ func NewExportCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.container = args[0]
-			return runExport(dockerCli, opts)
+			return runExport(cmd.Context(), dockerCli, opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container export, docker export",
@@ -41,7 +41,7 @@ func NewExportCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runExport(dockerCli command.Cli, opts exportOptions) error {
+func runExport(ctx context.Context, dockerCli command.Cli, opts exportOptions) error {
 	if opts.output == "" && dockerCli.Out().IsTerminal() {
 		return errors.New("cowardly refusing to save to a terminal. Use the -o flag or redirect")
 	}
@@ -52,7 +52,7 @@ func runExport(dockerCli command.Cli, opts exportOptions) error {
 
 	clnt := dockerCli.Client()
 
-	responseBody, err := clnt.ContainerExport(context.Background(), opts.container)
+	responseBody, err := clnt.ContainerExport(ctx, opts.container)
 	if err != nil {
 		return err
 	}

cli/command/container/inspect.go

@@ -1,3 +1,6 @@
+// FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
+//go:build go1.19
+
 package container
 
 import (
@@ -27,7 +30,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.refs = args
-			return runInspect(dockerCli, opts)
+			return runInspect(cmd.Context(), dockerCli, opts)
 		},
 		ValidArgsFunction: completion.ContainerNames(dockerCli, true),
 	}
@@ -39,9 +42,8 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runInspect(dockerCli command.Cli, opts inspectOptions) error {
+func runInspect(ctx context.Context, dockerCli command.Cli, opts inspectOptions) error {
 	client := dockerCli.Client()
-	ctx := context.Background()
 
 	getRefFunc := func(ref string) (any, []byte, error) {
 		return client.ContainerInspectWithRaw(ctx, ref, opts.size)

cli/command/container/kill.go

@@ -28,7 +28,7 @@ func NewKillCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.containers = args
-			return runKill(dockerCli, &opts)
+			return runKill(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container kill, docker kill",
@@ -41,9 +41,8 @@ func NewKillCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runKill(dockerCli command.Cli, opts *killOptions) error {
+func runKill(ctx context.Context, dockerCli command.Cli, opts *killOptions) error {
 	var errs []string
-	ctx := context.Background()
 	errChan := parallelOperation(ctx, opts.containers, func(ctx context.Context, container string) error {
 		return dockerCli.Client().ContainerKill(ctx, container, opts.signal)
 	})

cli/command/container/list.go

@@ -38,7 +38,7 @@ func NewPsCommand(dockerCLI command.Cli) *cobra.Command {
 		Args:  cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			options.sizeChanged = cmd.Flags().Changed("size")
-			return runPs(dockerCLI, &options)
+			return runPs(cmd.Context(), dockerCLI, &options)
 		},
 		Annotations: map[string]string{
 			"category-top": "3",
@@ -114,9 +114,7 @@ func buildContainerListOptions(options *psOptions) (*container.ListOptions, erro
 	return listOptions, nil
 }
 
-func runPs(dockerCLI command.Cli, options *psOptions) error {
-	ctx := context.Background()
-
+func runPs(ctx context.Context, dockerCLI command.Cli, options *psOptions) error {
 	if len(options.format) == 0 {
 		// load custom psFormat from CLI config (if any)
 		options.format = dockerCLI.ConfigFile().PsFormat

cli/command/container/logs.go

@@ -33,7 +33,7 @@ func NewLogsCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.container = args[0]
-			return runLogs(dockerCli, &opts)
+			return runLogs(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container logs, docker logs",
@@ -52,9 +52,7 @@ func NewLogsCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runLogs(dockerCli command.Cli, opts *logsOptions) error {
-	ctx := context.Background()
-
+func runLogs(ctx context.Context, dockerCli command.Cli, opts *logsOptions) error {
 	c, err := dockerCli.Client().ContainerInspect(ctx, opts.container)
 	if err != nil {
 		return err

cli/command/container/logs_test.go

@@ -1,6 +1,7 @@
 package container
 
 import (
+	"context"
 	"io"
 	"strings"
 	"testing"
@@ -46,7 +47,7 @@ func TestRunLogs(t *testing.T) {
 		t.Run(testcase.doc, func(t *testing.T) {
 			cli := test.NewFakeCli(&testcase.client)
 
-			err := runLogs(cli, testcase.options)
+			err := runLogs(context.TODO(), cli, testcase.options)
 			if testcase.expectedError != "" {
 				assert.ErrorContains(t, err, testcase.expectedError)
 			} else if !assert.Check(t, err) {

cli/command/container/opts.go

@@ -28,6 +28,20 @@ import (
 	cdi "tags.cncf.io/container-device-interface/pkg/parser"
 )
 
+const (
+	// TODO(thaJeztah): define these in the API-types, or query available defaults
+	//  from the daemon, or require "local" profiles to be an absolute path or
+	//  relative paths starting with "./". The daemon-config has consts for this
+	//  but we don't want to import that package:
+	//  https://github.com/moby/moby/blob/v23.0.0/daemon/config/config.go#L63-L67
+
+	// seccompProfileDefault is the built-in default seccomp profile.
+	seccompProfileDefault = "builtin"
+	// seccompProfileUnconfined is a special profile name for seccomp to use an
+	// "unconfined" seccomp profile.
+	seccompProfileUnconfined = "unconfined"
+)
+
 var deviceCgroupRuleRegexp = regexp.MustCompile(`^[acb] ([0-9]+|\*):([0-9]+|\*) [rwm]{1,3}$`)
 
 // containerOptions is a data object with all the options for creating a container
@@ -914,16 +928,23 @@ func parseSecurityOpts(securityOpts []string) ([]string, error) {
 			// "no-new-privileges" is the only option that does not require a value.
 			return securityOpts, errors.Errorf("Invalid --security-opt: %q", opt)
 		}
-		if k == "seccomp" && v != "unconfined" {
-			f, err := os.ReadFile(v)
-			if err != nil {
-				return securityOpts, errors.Errorf("opening seccomp profile (%s) failed: %v", v, err)
+		if k == "seccomp" {
+			switch v {
+			case seccompProfileDefault, seccompProfileUnconfined:
+				// known special names for built-in profiles, nothing to do.
+			default:
+				// value may be a filename, in which case we send the profile's
+				// content if it's valid JSON.
+				f, err := os.ReadFile(v)
+				if err != nil {
+					return securityOpts, errors.Errorf("opening seccomp profile (%s) failed: %v", v, err)
+				}
+				b := bytes.NewBuffer(nil)
+				if err := json.Compact(b, f); err != nil {
+					return securityOpts, errors.Errorf("compacting json for seccomp profile (%s) failed: %v", v, err)
+				}
+				securityOpts[key] = fmt.Sprintf("seccomp=%s", b.Bytes())
 			}
-			b := bytes.NewBuffer(nil)
-			if err := json.Compact(b, f); err != nil {
-				return securityOpts, errors.Errorf("compacting json for seccomp profile (%s) failed: %v", v, err)
-			}
-			securityOpts[key] = fmt.Sprintf("seccomp=%s", b.Bytes())
 		}
 	}
 

cli/command/container/pause.go

@@ -27,7 +27,7 @@ func NewPauseCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.containers = args
-			return runPause(dockerCli, &opts)
+			return runPause(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container pause, docker pause",
@@ -38,9 +38,7 @@ func NewPauseCommand(dockerCli command.Cli) *cobra.Command {
 	}
 }
 
-func runPause(dockerCli command.Cli, opts *pauseOptions) error {
-	ctx := context.Background()
-
+func runPause(ctx context.Context, dockerCli command.Cli, opts *pauseOptions) error {
 	var errs []string
 	errChan := parallelOperation(ctx, opts.containers, dockerCli.Client().ContainerPause)
 	for _, container := range opts.containers {

cli/command/container/port.go

@@ -36,7 +36,7 @@ func NewPortCommand(dockerCli command.Cli) *cobra.Command {
 			if len(args) > 1 {
 				opts.port = args[1]
 			}
-			return runPort(dockerCli, &opts)
+			return runPort(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container port, docker port",
@@ -52,9 +52,7 @@ func NewPortCommand(dockerCli command.Cli) *cobra.Command {
 // TODO(thaJeztah): currently this defaults to show the TCP port if no
 // proto is specified. We should consider changing this to "any" protocol
 // for the given private port.
-func runPort(dockerCli command.Cli, opts *portOptions) error {
-	ctx := context.Background()
-
+func runPort(ctx context.Context, dockerCli command.Cli, opts *portOptions) error {
 	c, err := dockerCli.Client().ContainerInspect(ctx, opts.container)
 	if err != nil {
 		return err

cli/command/container/prune.go

@@ -26,7 +26,7 @@ func NewPruneCommand(dockerCli command.Cli) *cobra.Command {
 		Short: "Remove all stopped containers",
 		Args:  cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			spaceReclaimed, output, err := runPrune(dockerCli, options)
+			spaceReclaimed, output, err := runPrune(cmd.Context(), dockerCli, options)
 			if err != nil {
 				return err
 			}
@@ -50,14 +50,14 @@ func NewPruneCommand(dockerCli command.Cli) *cobra.Command {
 const warning = `WARNING! This will remove all stopped containers.
 Are you sure you want to continue?`
 
-func runPrune(dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint64, output string, err error) {
+func runPrune(ctx context.Context, dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint64, output string, err error) {
 	pruneFilters := command.PruneFilters(dockerCli, options.filter.Value())
 
 	if !options.force && !command.PromptForConfirmation(dockerCli.In(), dockerCli.Out(), warning) {
 		return 0, "", nil
 	}
 
-	report, err := dockerCli.Client().ContainersPrune(context.Background(), pruneFilters)
+	report, err := dockerCli.Client().ContainersPrune(ctx, pruneFilters)
 	if err != nil {
 		return 0, "", err
 	}
@@ -75,6 +75,6 @@ func runPrune(dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint6
 
 // RunPrune calls the Container Prune API
 // This returns the amount of space reclaimed and a detailed output string
-func RunPrune(dockerCli command.Cli, _ bool, filter opts.FilterOpt) (uint64, string, error) {
-	return runPrune(dockerCli, pruneOptions{force: true, filter: filter})
+func RunPrune(ctx context.Context, dockerCli command.Cli, _ bool, filter opts.FilterOpt) (uint64, string, error) {
+	return runPrune(ctx, dockerCli, pruneOptions{force: true, filter: filter})
 }

cli/command/container/rename.go

@@ -28,7 +28,7 @@ func NewRenameCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.oldName = args[0]
 			opts.newName = args[1]
-			return runRename(dockerCli, &opts)
+			return runRename(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container rename, docker rename",
@@ -38,9 +38,7 @@ func NewRenameCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runRename(dockerCli command.Cli, opts *renameOptions) error {
-	ctx := context.Background()
-
+func runRename(ctx context.Context, dockerCli command.Cli, opts *renameOptions) error {
 	oldName := strings.TrimSpace(opts.oldName)
 	newName := strings.TrimSpace(opts.newName)
 

cli/command/container/restart.go

@@ -32,7 +32,7 @@ func NewRestartCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.containers = args
 			opts.timeoutChanged = cmd.Flags().Changed("time")
-			return runRestart(dockerCli, &opts)
+			return runRestart(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container restart, docker restart",
@@ -46,8 +46,7 @@ func NewRestartCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runRestart(dockerCli command.Cli, opts *restartOptions) error {
-	ctx := context.Background()
+func runRestart(ctx context.Context, dockerCli command.Cli, opts *restartOptions) error {
 	var errs []string
 	var timeout *int
 	if opts.timeoutChanged {

cli/command/container/rm.go

@@ -33,7 +33,7 @@ func NewRmCommand(dockerCli command.Cli) *cobra.Command {
 		Args:    cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.containers = args
-			return runRm(dockerCli, &opts)
+			return runRm(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container rm, docker container remove, docker rm",
@@ -48,9 +48,7 @@ func NewRmCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runRm(dockerCli command.Cli, opts *rmOptions) error {
-	ctx := context.Background()
-
+func runRm(ctx context.Context, dockerCli command.Cli, opts *rmOptions) error {
 	var errs []string
 	errChan := parallelOperation(ctx, opts.containers, func(ctx context.Context, ctrID string) error {
 		ctrID = strings.Trim(ctrID, "/")

cli/command/container/run.go

@@ -42,7 +42,7 @@ func NewRunCommand(dockerCli command.Cli) *cobra.Command {
 			if len(args) > 1 {
 				copts.Args = args[1:]
 			}
-			return runRun(dockerCli, cmd.Flags(), &options, copts)
+			return runRun(cmd.Context(), dockerCli, cmd.Flags(), &options, copts)
 		},
 		ValidArgsFunction: completion.ImageNames(dockerCli),
 		Annotations: map[string]string{
@@ -89,7 +89,7 @@ func NewRunCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runRun(dockerCli command.Cli, flags *pflag.FlagSet, ropts *runOptions, copts *containerOptions) error {
+func runRun(ctx context.Context, dockerCli command.Cli, flags *pflag.FlagSet, ropts *runOptions, copts *containerOptions) error {
 	if err := validatePullOpt(ropts.pull); err != nil {
 		reportError(dockerCli.Err(), "run", err.Error(), true)
 		return cli.StatusError{StatusCode: 125}
@@ -114,11 +114,11 @@ func runRun(dockerCli command.Cli, flags *pflag.FlagSet, ropts *runOptions, copt
 		reportError(dockerCli.Err(), "run", err.Error(), true)
 		return cli.StatusError{StatusCode: 125}
 	}
-	return runContainer(dockerCli, ropts, copts, containerCfg)
+	return runContainer(ctx, dockerCli, ropts, copts, containerCfg)
 }
 
 //nolint:gocyclo
-func runContainer(dockerCli command.Cli, runOpts *runOptions, copts *containerOptions, containerCfg *containerConfig) error {
+func runContainer(ctx context.Context, dockerCli command.Cli, runOpts *runOptions, copts *containerOptions, containerCfg *containerConfig) error {
 	config := containerCfg.Config
 	stdout, stderr := dockerCli.Out(), dockerCli.Err()
 	apiClient := dockerCli.Client()
@@ -140,7 +140,7 @@ func runContainer(dockerCli command.Cli, runOpts *runOptions, copts *containerOp
 		config.StdinOnce = false
 	}
 
-	ctx, cancelFun := context.WithCancel(context.Background())
+	ctx, cancelFun := context.WithCancel(ctx)
 	defer cancelFun()
 
 	containerID, err := createContainer(ctx, dockerCli, containerCfg, &runOpts.createOptions)

cli/command/container/run_test.go

@@ -1,6 +1,7 @@
 package container
 
 import (
+	"context"
 	"errors"
 	"fmt"
 	"io"
@@ -97,6 +98,7 @@ func TestRunContainerImagePullPolicyInvalid(t *testing.T) {
 		t.Run(tc.PullPolicy, func(t *testing.T) {
 			dockerCli := test.NewFakeCli(&fakeClient{})
 			err := runRun(
+				context.TODO(),
 				dockerCli,
 				&pflag.FlagSet{},
 				&runOptions{createOptions: createOptions{pull: tc.PullPolicy}},

cli/command/container/start.go

@@ -45,7 +45,7 @@ func NewStartCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Containers = args
-			return RunStart(dockerCli, &opts)
+			return RunStart(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container start, docker start",
@@ -72,8 +72,8 @@ func NewStartCommand(dockerCli command.Cli) *cobra.Command {
 // RunStart executes a `start` command
 //
 //nolint:gocyclo
-func RunStart(dockerCli command.Cli, opts *StartOptions) error {
-	ctx, cancelFun := context.WithCancel(context.Background())
+func RunStart(ctx context.Context, dockerCli command.Cli, opts *StartOptions) error {
+	ctx, cancelFun := context.WithCancel(ctx)
 	defer cancelFun()
 
 	switch {

cli/command/container/stats.go

@@ -21,83 +21,94 @@ import (
 	"github.com/spf13/cobra"
 )
 
-type statsOptions struct {
-	all        bool
-	noStream   bool
-	noTrunc    bool
-	format     string
-	containers []string
+// StatsOptions defines options for [RunStats].
+type StatsOptions struct {
+	// All allows including both running and stopped containers. The default
+	// is to only include running containers.
+	All bool
+
+	// NoStream disables streaming stats. If enabled, stats are collected once,
+	// and the result is printed.
+	NoStream bool
+
+	// NoTrunc disables truncating the output. The default is to truncate
+	// output such as container-IDs.
+	NoTrunc bool
+
+	// Format is a custom template to use for presenting the stats.
+	// Refer to [flagsHelper.FormatHelp] for accepted formats.
+	Format string
+
+	// Containers is the list of container names or IDs to include in the stats.
+	// If empty, all containers are included. It is mutually exclusive with the
+	// Filters option, and an error is produced if both are set.
+	Containers []string
+
+	// Filters provides optional filters to filter the list of containers and their
+	// associated container-events to include in the stats if no list of containers
+	// is set. If no filter is provided, all containers are included. Filters and
+	// Containers are currently mutually exclusive, and setting both options
+	// produces an error.
+	//
+	// These filters are used both to collect the initial list of containers and
+	// to refresh the list of containers based on container-events, accepted
+	// filters are limited to the intersection of filters accepted by "events"
+	// and "container list".
+	//
+	// Currently only "label" / "label=value" filters are accepted. Additional
+	// filter options may be added in future (within the constraints described
+	// above), but may require daemon-side validation as the list of accepted
+	// filters can differ between daemon- and API versions.
+	Filters *filters.Args
 }
 
-// NewStatsCommand creates a new cobra.Command for `docker stats`
-func NewStatsCommand(dockerCli command.Cli) *cobra.Command {
-	var opts statsOptions
+// NewStatsCommand creates a new [cobra.Command] for "docker stats".
+func NewStatsCommand(dockerCLI command.Cli) *cobra.Command {
+	options := StatsOptions{}
 
 	cmd := &cobra.Command{
 		Use:   "stats [OPTIONS] [CONTAINER...]",
 		Short: "Display a live stream of container(s) resource usage statistics",
 		Args:  cli.RequiresMinArgs(0),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			opts.containers = args
-			return runStats(dockerCli, &opts)
+			options.Containers = args
+			return RunStats(cmd.Context(), dockerCLI, &options)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container stats, docker stats",
 		},
-		ValidArgsFunction: completion.ContainerNames(dockerCli, false),
+		ValidArgsFunction: completion.ContainerNames(dockerCLI, false),
 	}
 
 	flags := cmd.Flags()
-	flags.BoolVarP(&opts.all, "all", "a", false, "Show all containers (default shows just running)")
-	flags.BoolVar(&opts.noStream, "no-stream", false, "Disable streaming stats and only pull the first result")
-	flags.BoolVar(&opts.noTrunc, "no-trunc", false, "Do not truncate output")
-	flags.StringVar(&opts.format, "format", "", flagsHelper.FormatHelp)
+	flags.BoolVarP(&options.All, "all", "a", false, "Show all containers (default shows just running)")
+	flags.BoolVar(&options.NoStream, "no-stream", false, "Disable streaming stats and only pull the first result")
+	flags.BoolVar(&options.NoTrunc, "no-trunc", false, "Do not truncate output")
+	flags.StringVar(&options.Format, "format", "", flagsHelper.FormatHelp)
 	return cmd
 }
 
-// runStats displays a live stream of resource usage statistics for one or more containers.
+// acceptedStatsFilters is the list of filters accepted by [RunStats] (through
+// the [StatsOptions.Filters] option).
+//
+// TODO(thaJeztah): don't hard-code the list of accept filters, and expand
+// to the intersection of filters accepted by both "container list" and
+// "system events". Validating filters may require an initial API call
+// to both endpoints ("container list" and "system events").
+var acceptedStatsFilters = map[string]bool{
+	"label": true,
+}
+
+// RunStats displays a live stream of resource usage statistics for one or more containers.
 // This shows real-time information on CPU usage, memory usage, and network I/O.
 //
 //nolint:gocyclo
-func runStats(dockerCli command.Cli, opts *statsOptions) error {
-	showAll := len(opts.containers) == 0
-	closeChan := make(chan error)
-
-	ctx := context.Background()
-
-	// monitorContainerEvents watches for container creation and removal (only
-	// used when calling `docker stats` without arguments).
-	monitorContainerEvents := func(started chan<- struct{}, c chan events.Message, stopped <-chan struct{}) {
-		f := filters.NewArgs()
-		f.Add("type", "container")
-		options := types.EventsOptions{
-			Filters: f,
-		}
-
-		eventq, errq := dockerCli.Client().Events(ctx, options)
-
-		// Whether we successfully subscribed to eventq or not, we can now
-		// unblock the main goroutine.
-		close(started)
-		defer close(c)
-
-		for {
-			select {
-			case <-stopped:
-				return
-			case event := <-eventq:
-				c <- event
-			case err := <-errq:
-				closeChan <- err
-				return
-			}
-		}
-	}
+func RunStats(ctx context.Context, dockerCLI command.Cli, options *StatsOptions) error {
+	apiClient := dockerCLI.Client()
 
 	// Get the daemonOSType if not set already
 	if daemonOSType == "" {
-		svctx := context.Background()
-		sv, err := dockerCli.Client().ServerVersion(svctx)
+		sv, err := apiClient.ServerVersion(ctx)
 		if err != nil {
 			return err
 		}
@@ -106,57 +117,82 @@ func runStats(dockerCli command.Cli, opts *statsOptions) error {
 
 	// waitFirst is a WaitGroup to wait first stat data's reach for each container
 	waitFirst := &sync.WaitGroup{}
-
+	// closeChan is a non-buffered channel used to collect errors from goroutines.
+	closeChan := make(chan error)
 	cStats := stats{}
-	// getContainerList simulates creation event for all previously existing
-	// containers (only used when calling `docker stats` without arguments).
-	getContainerList := func() {
-		options := container.ListOptions{
-			All: opts.all,
-		}
-		cs, err := dockerCli.Client().ContainerList(ctx, options)
-		if err != nil {
-			closeChan <- err
-		}
-		for _, ctr := range cs {
-			s := NewStats(ctr.ID[:12])
-			if cStats.add(s) {
-				waitFirst.Add(1)
-				go collect(ctx, s, dockerCli.Client(), !opts.noStream, waitFirst)
-			}
-		}
-	}
 
+	showAll := len(options.Containers) == 0
 	if showAll {
-		// If no names were specified, start a long running goroutine which
+		// If no names were specified, start a long-running goroutine which
 		// monitors container events. We make sure we're subscribed before
 		// retrieving the list of running containers to avoid a race where we
 		// would "miss" a creation.
 		started := make(chan struct{})
+
+		if options.Filters == nil {
+			f := filters.NewArgs()
+			options.Filters = &f
+		}
+
+		if err := options.Filters.Validate(acceptedStatsFilters); err != nil {
+			return err
+		}
+
 		eh := command.InitEventHandler()
-		eh.Handle(events.ActionCreate, func(e events.Message) {
-			if opts.all {
+		if options.All {
+			eh.Handle(events.ActionCreate, func(e events.Message) {
 				s := NewStats(e.Actor.ID[:12])
 				if cStats.add(s) {
 					waitFirst.Add(1)
-					go collect(ctx, s, dockerCli.Client(), !opts.noStream, waitFirst)
+					go collect(ctx, s, apiClient, !options.NoStream, waitFirst)
 				}
-			}
-		})
+			})
+		}
 
 		eh.Handle(events.ActionStart, func(e events.Message) {
 			s := NewStats(e.Actor.ID[:12])
 			if cStats.add(s) {
 				waitFirst.Add(1)
-				go collect(ctx, s, dockerCli.Client(), !opts.noStream, waitFirst)
+				go collect(ctx, s, apiClient, !options.NoStream, waitFirst)
 			}
 		})
 
-		eh.Handle(events.ActionDie, func(e events.Message) {
-			if !opts.all {
+		if !options.All {
+			eh.Handle(events.ActionDie, func(e events.Message) {
 				cStats.remove(e.Actor.ID[:12])
+			})
+		}
+
+		// monitorContainerEvents watches for container creation and removal (only
+		// used when calling `docker stats` without arguments).
+		monitorContainerEvents := func(started chan<- struct{}, c chan events.Message, stopped <-chan struct{}) {
+			// Create a copy of the custom filters so that we don't mutate
+			// the original set of filters. Custom filters are used both
+			// to list containers and to filter events, but the "type" filter
+			// is not valid for filtering containers.
+			f := options.Filters.Clone()
+			f.Add("type", string(events.ContainerEventType))
+			eventChan, errChan := apiClient.Events(ctx, types.EventsOptions{
+				Filters: f,
+			})
+
+			// Whether we successfully subscribed to eventChan or not, we can now
+			// unblock the main goroutine.
+			close(started)
+			defer close(c)
+
+			for {
+				select {
+				case <-stopped:
+					return
+				case event := <-eventChan:
+					c <- event
+				case err := <-errChan:
+					closeChan <- err
+					return
+				}
 			}
-		})
+		}
 
 		eventChan := make(chan events.Message)
 		go eh.Watch(eventChan)
@@ -165,20 +201,42 @@ func runStats(dockerCli command.Cli, opts *statsOptions) error {
 		defer close(stopped)
 		<-started
 
-		// Start a short-lived goroutine to retrieve the initial list of
-		// containers.
-		getContainerList()
+		// Fetch the initial list of containers and collect stats for them.
+		// After the initial list was collected, we start listening for events
+		// to refresh the list of containers.
+		cs, err := apiClient.ContainerList(ctx, container.ListOptions{
+			All:     options.All,
+			Filters: *options.Filters,
+		})
+		if err != nil {
+			return err
+		}
+		for _, ctr := range cs {
+			s := NewStats(ctr.ID[:12])
+			if cStats.add(s) {
+				waitFirst.Add(1)
+				go collect(ctx, s, apiClient, !options.NoStream, waitFirst)
+			}
+		}
 
 		// make sure each container get at least one valid stat data
 		waitFirst.Wait()
 	} else {
-		// Artificially send creation events for the containers we were asked to
-		// monitor (same code path than we use when monitoring all containers).
-		for _, name := range opts.containers {
-			s := NewStats(name)
+		// TODO(thaJeztah): re-implement options.Containers as a filter so that
+		// only a single code-path is needed, and custom filters can be combined
+		// with a list of container names/IDs.
+
+		if options.Filters != nil && options.Filters.Len() > 0 {
+			return fmt.Errorf("filtering is not supported when specifying a list of containers")
+		}
+
+		// Create the list of containers, and start collecting stats for all
+		// containers passed.
+		for _, ctr := range options.Containers {
+			s := NewStats(ctr)
 			if cStats.add(s) {
 				waitFirst.Add(1)
-				go collect(ctx, s, dockerCli.Client(), !opts.noStream, waitFirst)
+				go collect(ctx, s, apiClient, !options.NoStream, waitFirst)
 			}
 		}
 
@@ -201,22 +259,22 @@ func runStats(dockerCli command.Cli, opts *statsOptions) error {
 		}
 	}
 
-	format := opts.format
+	format := options.Format
 	if len(format) == 0 {
-		if len(dockerCli.ConfigFile().StatsFormat) > 0 {
-			format = dockerCli.ConfigFile().StatsFormat
+		if len(dockerCLI.ConfigFile().StatsFormat) > 0 {
+			format = dockerCLI.ConfigFile().StatsFormat
 		} else {
 			format = formatter.TableFormatKey
 		}
 	}
 	statsCtx := formatter.Context{
-		Output: dockerCli.Out(),
+		Output: dockerCLI.Out(),
 		Format: NewStatsFormat(format, daemonOSType),
 	}
 	cleanScreen := func() {
-		if !opts.noStream {
-			fmt.Fprint(dockerCli.Out(), "\033[2J")
-			fmt.Fprint(dockerCli.Out(), "\033[H")
+		if !options.NoStream {
+			_, _ = fmt.Fprint(dockerCLI.Out(), "\033[2J")
+			_, _ = fmt.Fprint(dockerCLI.Out(), "\033[H")
 		}
 	}
 
@@ -225,28 +283,28 @@ func runStats(dockerCli command.Cli, opts *statsOptions) error {
 	defer ticker.Stop()
 	for range ticker.C {
 		cleanScreen()
-		ccstats := []StatsEntry{}
+		var ccStats []StatsEntry
 		cStats.mu.RLock()
 		for _, c := range cStats.cs {
-			ccstats = append(ccstats, c.GetStatistics())
+			ccStats = append(ccStats, c.GetStatistics())
 		}
 		cStats.mu.RUnlock()
-		if err = statsFormatWrite(statsCtx, ccstats, daemonOSType, !opts.noTrunc); err != nil {
+		if err = statsFormatWrite(statsCtx, ccStats, daemonOSType, !options.NoTrunc); err != nil {
 			break
 		}
 		if len(cStats.cs) == 0 && !showAll {
 			break
 		}
-		if opts.noStream {
+		if options.NoStream {
 			break
 		}
 		select {
 		case err, ok := <-closeChan:
 			if ok {
 				if err != nil {
-					// this is suppressing "unexpected EOF" in the cli when the
-					// daemon restarts so it shutdowns cleanly
-					if err == io.ErrUnexpectedEOF {
+					// Suppress "unexpected EOF" errors in the CLI so that
+					// it shuts down cleanly when the daemon restarts.
+					if errors.Is(err, io.ErrUnexpectedEOF) {
 						return nil
 					}
 					return err

cli/command/container/stop.go

@@ -32,7 +32,7 @@ func NewStopCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.containers = args
 			opts.timeoutChanged = cmd.Flags().Changed("time")
-			return runStop(dockerCli, &opts)
+			return runStop(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container stop, docker stop",
@@ -46,13 +46,13 @@ func NewStopCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runStop(dockerCli command.Cli, opts *stopOptions) error {
+func runStop(ctx context.Context, dockerCli command.Cli, opts *stopOptions) error {
 	var timeout *int
 	if opts.timeoutChanged {
 		timeout = &opts.timeout
 	}
 
-	errChan := parallelOperation(context.Background(), opts.containers, func(ctx context.Context, id string) error {
+	errChan := parallelOperation(ctx, opts.containers, func(ctx context.Context, id string) error {
 		return dockerCli.Client().ContainerStop(ctx, id, container.StopOptions{
 			Signal:  opts.signal,
 			Timeout: timeout,

cli/command/container/top.go

@@ -29,7 +29,7 @@ func NewTopCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.container = args[0]
 			opts.args = args[1:]
-			return runTop(dockerCli, &opts)
+			return runTop(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container top, docker top",
@@ -43,9 +43,7 @@ func NewTopCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runTop(dockerCli command.Cli, opts *topOptions) error {
-	ctx := context.Background()
-
+func runTop(ctx context.Context, dockerCli command.Cli, opts *topOptions) error {
 	procList, err := dockerCli.Client().ContainerTop(ctx, opts.container, opts.args)
 	if err != nil {
 		return err

cli/command/container/unpause.go

@@ -27,7 +27,7 @@ func NewUnpauseCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.containers = args
-			return runUnpause(dockerCli, &opts)
+			return runUnpause(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container unpause, docker unpause",
@@ -39,9 +39,7 @@ func NewUnpauseCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runUnpause(dockerCli command.Cli, opts *unpauseOptions) error {
-	ctx := context.Background()
-
+func runUnpause(ctx context.Context, dockerCli command.Cli, opts *unpauseOptions) error {
 	var errs []string
 	errChan := parallelOperation(ctx, opts.containers, dockerCli.Client().ContainerUnpause)
 	for _, container := range opts.containers {

cli/command/container/update.go

@@ -47,7 +47,7 @@ func NewUpdateCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			options.containers = args
 			options.nFlag = cmd.Flags().NFlag()
-			return runUpdate(dockerCli, &options)
+			return runUpdate(cmd.Context(), dockerCli, &options)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container update, docker update",
@@ -86,7 +86,7 @@ func NewUpdateCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runUpdate(dockerCli command.Cli, options *updateOptions) error {
+func runUpdate(ctx context.Context, dockerCli command.Cli, options *updateOptions) error {
 	var err error
 
 	if options.nFlag == 0 {
@@ -126,8 +126,6 @@ func runUpdate(dockerCli command.Cli, options *updateOptions) error {
 		RestartPolicy: restartPolicy,
 	}
 
-	ctx := context.Background()
-
 	var (
 		warns []string
 		errs  []string

cli/command/container/wait.go

@@ -26,7 +26,7 @@ func NewWaitCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.containers = args
-			return runWait(dockerCli, &opts)
+			return runWait(cmd.Context(), dockerCli, &opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker container wait, docker wait",
@@ -37,9 +37,7 @@ func NewWaitCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runWait(dockerCli command.Cli, opts *waitOptions) error {
-	ctx := context.Background()
-
+func runWait(ctx context.Context, dockerCli command.Cli, opts *waitOptions) error {
 	var errs []string
 	for _, container := range opts.containers {
 		resultC, errC := dockerCli.Client().ContainerWait(ctx, container, "")

cli/command/context.go

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

cli/command/context/create.go

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

cli/command/context/create_test.go

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

cli/command/context/inspect.go

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

cli/command/context_test.go

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

cli/command/defaultcontextstore.go

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

cli/command/defaultcontextstore_test.go

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

cli/command/formatter/container.go

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

cli/command/formatter/container_test.go

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

cli/command/formatter/custom.go

@@ -1,3 +1,6 @@
+// FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
+//go:build go1.19
+
 package formatter
 
 import "strings"

cli/command/formatter/formatter.go

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

cli/command/formatter/formatter_test.go

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

cli/command/formatter/reflect.go

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

cli/command/formatter/reflect_test.go

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

cli/command/formatter/volume_test.go

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

cli/command/idresolver/idresolver.go

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

cli/command/image/build.go

@@ -101,7 +101,7 @@ func NewBuildCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			options.context = args[0]
-			return runBuild(dockerCli, options)
+			return runBuild(cmd.Context(), dockerCli, options)
 		},
 		Annotations: map[string]string{
 			"category-top": "4",
@@ -172,7 +172,7 @@ func (out *lastProgressOutput) WriteProgress(prog progress.Progress) error {
 }
 
 //nolint:gocyclo
-func runBuild(dockerCli command.Cli, options buildOptions) error {
+func runBuild(ctx context.Context, dockerCli command.Cli, options buildOptions) error {
 	var (
 		err           error
 		buildCtx      io.ReadCloser
@@ -272,7 +272,7 @@ func runBuild(dockerCli command.Cli, options buildOptions) error {
 		}
 	}
 
-	ctx, cancel := context.WithCancel(context.Background())
+	ctx, cancel := context.WithCancel(ctx)
 	defer cancel()
 
 	var resolvedTags []*resolvedTag

cli/command/image/build/context.go

@@ -234,7 +234,8 @@ func GetContextFromURL(out io.Writer, remoteURL, dockerfileName string) (io.Read
 // getWithStatusError does an http.Get() and returns an error if the
 // status code is 4xx or 5xx.
 func getWithStatusError(url string) (resp *http.Response, err error) {
-	if resp, err = http.Get(url); err != nil { //nolint:gosec // Ignore G107: Potential HTTP request made with variable url
+	//#nosec G107 -- Ignore G107: Potential HTTP request made with variable url
+	if resp, err = http.Get(url); err != nil {
 		return nil, err
 	}
 	if resp.StatusCode < http.StatusBadRequest {

cli/command/image/build_test.go

@@ -48,7 +48,7 @@ func TestRunBuildDockerfileFromStdinWithCompress(t *testing.T) {
 	options.dockerfileName = "-"
 	options.context = dir.Path()
 	options.untrusted = true
-	assert.NilError(t, runBuild(cli, options))
+	assert.NilError(t, runBuild(context.TODO(), cli, options))
 
 	expected := []string{fakeBuild.options.Dockerfile, ".dockerignore", "foo"}
 	assert.DeepEqual(t, expected, fakeBuild.filenames(t))
@@ -75,7 +75,7 @@ func TestRunBuildResetsUidAndGidInContext(t *testing.T) {
 	options := newBuildOptions()
 	options.context = dir.Path()
 	options.untrusted = true
-	assert.NilError(t, runBuild(cli, options))
+	assert.NilError(t, runBuild(context.TODO(), cli, options))
 
 	headers := fakeBuild.headers(t)
 	expected := []*tar.Header{
@@ -110,7 +110,7 @@ COPY data /data
 	options.context = dir.Path()
 	options.dockerfileName = df.Path()
 	options.untrusted = true
-	assert.NilError(t, runBuild(cli, options))
+	assert.NilError(t, runBuild(context.TODO(), cli, options))
 
 	expected := []string{fakeBuild.options.Dockerfile, ".dockerignore", "data"}
 	assert.DeepEqual(t, expected, fakeBuild.filenames(t))
@@ -170,7 +170,7 @@ RUN echo hello world
 	options := newBuildOptions()
 	options.context = tmpDir.Join("context-link")
 	options.untrusted = true
-	assert.NilError(t, runBuild(cli, options))
+	assert.NilError(t, runBuild(context.TODO(), cli, options))
 
 	assert.DeepEqual(t, fakeBuild.filenames(t), []string{"Dockerfile"})
 }

cli/command/image/history.go

@@ -29,7 +29,7 @@ func NewHistoryCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.image = args[0]
-			return runHistory(dockerCli, opts)
+			return runHistory(cmd.Context(), dockerCli, opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker image history, docker history",
@@ -46,9 +46,7 @@ func NewHistoryCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runHistory(dockerCli command.Cli, opts historyOptions) error {
-	ctx := context.Background()
-
+func runHistory(ctx context.Context, dockerCli command.Cli, opts historyOptions) error {
 	history, err := dockerCli.Client().ImageHistory(ctx, opts.image)
 	if err != nil {
 		return err

cli/command/image/import.go

@@ -34,7 +34,7 @@ func NewImportCommand(dockerCli command.Cli) *cobra.Command {
 			if len(args) > 1 {
 				options.reference = args[1]
 			}
-			return runImport(dockerCli, options)
+			return runImport(cmd.Context(), dockerCli, options)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker image import, docker import",
@@ -51,7 +51,7 @@ func NewImportCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runImport(dockerCli command.Cli, options importOptions) error {
+func runImport(ctx context.Context, dockerCli command.Cli, options importOptions) error {
 	var source types.ImageImportSource
 	switch {
 	case options.source == "-":
@@ -78,7 +78,7 @@ func runImport(dockerCli command.Cli, options importOptions) error {
 		}
 	}
 
-	responseBody, err := dockerCli.Client().ImageImport(context.Background(), source, options.reference, types.ImageImportOptions{
+	responseBody, err := dockerCli.Client().ImageImport(ctx, source, options.reference, types.ImageImportOptions{
 		Message:  options.message,
 		Changes:  options.changes.GetAll(),
 		Platform: options.platform,

cli/command/image/inspect.go

@@ -1,3 +1,6 @@
+// FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
+//go:build go1.19
+
 package image
 
 import (
@@ -25,7 +28,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.refs = args
-			return runInspect(dockerCli, opts)
+			return runInspect(cmd.Context(), dockerCli, opts)
 		},
 	}
 
@@ -34,10 +37,8 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runInspect(dockerCli command.Cli, opts inspectOptions) error {
+func runInspect(ctx context.Context, dockerCli command.Cli, opts inspectOptions) error {
 	client := dockerCli.Client()
-	ctx := context.Background()
-
 	getRefFunc := func(ref string) (any, []byte, error) {
 		return client.ImageInspectWithRaw(ctx, ref)
 	}

cli/command/image/list.go

@@ -35,7 +35,7 @@ func NewImagesCommand(dockerCli command.Cli) *cobra.Command {
 			if len(args) > 0 {
 				options.matchName = args[0]
 			}
-			return runImages(dockerCli, options)
+			return runImages(cmd.Context(), dockerCli, options)
 		},
 		Annotations: map[string]string{
 			"category-top": "7",
@@ -62,9 +62,7 @@ func newListCommand(dockerCli command.Cli) *cobra.Command {
 	return &cmd
 }
 
-func runImages(dockerCli command.Cli, options imagesOptions) error {
-	ctx := context.Background()
-
+func runImages(ctx context.Context, dockerCli command.Cli, options imagesOptions) error {
 	filters := options.filter.Value()
 	if options.matchName != "" {
 		filters.Add("reference", options.matchName)

cli/command/image/load.go

@@ -27,7 +27,7 @@ func NewLoadCommand(dockerCli command.Cli) *cobra.Command {
 		Short: "Load an image from a tar archive or STDIN",
 		Args:  cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runLoad(dockerCli, opts)
+			return runLoad(cmd.Context(), dockerCli, opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker image load, docker load",
@@ -43,7 +43,7 @@ func NewLoadCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runLoad(dockerCli command.Cli, opts loadOptions) error {
+func runLoad(ctx context.Context, dockerCli command.Cli, opts loadOptions) error {
 	var input io.Reader = dockerCli.In()
 	if opts.input != "" {
 		// We use sequential.Open to use sequential file access on Windows, avoiding
@@ -65,7 +65,7 @@ func runLoad(dockerCli command.Cli, opts loadOptions) error {
 	if !dockerCli.Out().IsTerminal() {
 		opts.quiet = true
 	}
-	response, err := dockerCli.Client().ImageLoad(context.Background(), input, opts.quiet)
+	response, err := dockerCli.Client().ImageLoad(ctx, input, opts.quiet)
 	if err != nil {
 		return err
 	}

cli/command/image/prune.go

@@ -29,7 +29,7 @@ func NewPruneCommand(dockerCli command.Cli) *cobra.Command {
 		Short: "Remove unused images",
 		Args:  cli.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			spaceReclaimed, output, err := runPrune(dockerCli, options)
+			spaceReclaimed, output, err := runPrune(cmd.Context(), dockerCli, options)
 			if err != nil {
 				return err
 			}
@@ -58,7 +58,7 @@ Are you sure you want to continue?`
 Are you sure you want to continue?`
 )
 
-func runPrune(dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint64, output string, err error) {
+func runPrune(ctx context.Context, dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint64, output string, err error) {
 	pruneFilters := options.filter.Value().Clone()
 	pruneFilters.Add("dangling", strconv.FormatBool(!options.all))
 	pruneFilters = command.PruneFilters(dockerCli, pruneFilters)
@@ -71,7 +71,7 @@ func runPrune(dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint6
 		return 0, "", nil
 	}
 
-	report, err := dockerCli.Client().ImagesPrune(context.Background(), pruneFilters)
+	report, err := dockerCli.Client().ImagesPrune(ctx, pruneFilters)
 	if err != nil {
 		return 0, "", err
 	}
@@ -99,6 +99,6 @@ func runPrune(dockerCli command.Cli, options pruneOptions) (spaceReclaimed uint6
 
 // RunPrune calls the Image Prune API
 // This returns the amount of space reclaimed and a detailed output string
-func RunPrune(dockerCli command.Cli, all bool, filter opts.FilterOpt) (uint64, string, error) {
-	return runPrune(dockerCli, pruneOptions{force: true, all: all, filter: filter})
+func RunPrune(ctx context.Context, dockerCli command.Cli, all bool, filter opts.FilterOpt) (uint64, string, error) {
+	return runPrune(ctx, dockerCli, pruneOptions{force: true, all: all, filter: filter})
 }

cli/command/image/pull.go

@@ -33,7 +33,7 @@ func NewPullCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.remote = args[0]
-			return RunPull(dockerCli, opts)
+			return RunPull(cmd.Context(), dockerCli, opts)
 		},
 		Annotations: map[string]string{
 			"category-top": "5",
@@ -54,7 +54,7 @@ func NewPullCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunPull performs a pull against the engine based on the specified options
-func RunPull(dockerCLI command.Cli, opts PullOptions) error {
+func RunPull(ctx context.Context, dockerCLI command.Cli, opts PullOptions) error {
 	distributionRef, err := reference.ParseNormalizedNamed(opts.remote)
 	switch {
 	case err != nil:
@@ -68,7 +68,6 @@ func RunPull(dockerCLI command.Cli, opts PullOptions) error {
 		}
 	}
 
-	ctx := context.Background()
 	imgRefAndAuth, err := trust.GetImageReferencesAndAuth(ctx, AuthResolver(dockerCLI), distributionRef.String())
 	if err != nil {
 		return err

cli/command/image/push.go

@@ -35,7 +35,7 @@ func NewPushCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.remote = args[0]
-			return RunPush(dockerCli, opts)
+			return RunPush(cmd.Context(), dockerCli, opts)
 		},
 		Annotations: map[string]string{
 			"category-top": "6",
@@ -53,7 +53,7 @@ func NewPushCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunPush performs a push against the engine based on the specified options
-func RunPush(dockerCli command.Cli, opts pushOptions) error {
+func RunPush(ctx context.Context, dockerCli command.Cli, opts pushOptions) error {
 	ref, err := reference.ParseNormalizedNamed(opts.remote)
 	switch {
 	case err != nil:
@@ -73,8 +73,6 @@ func RunPush(dockerCli command.Cli, opts pushOptions) error {
 		return err
 	}
 
-	ctx := context.Background()
-
 	// Resolve the Auth config relevant for this server
 	authConfig := command.ResolveAuthConfig(dockerCli.ConfigFile(), repoInfo.Index)
 	encodedAuth, err := registrytypes.EncodeAuthConfig(authConfig)

cli/command/image/remove.go

@@ -27,7 +27,7 @@ func NewRemoveCommand(dockerCli command.Cli) *cobra.Command {
 		Short: "Remove one or more images",
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runRemove(dockerCli, opts, args)
+			return runRemove(cmd.Context(), dockerCli, opts, args)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker image rm, docker image remove, docker rmi",
@@ -49,9 +49,8 @@ func newRemoveCommand(dockerCli command.Cli) *cobra.Command {
 	return &cmd
 }
 
-func runRemove(dockerCli command.Cli, opts removeOptions, images []string) error {
+func runRemove(ctx context.Context, dockerCli command.Cli, opts removeOptions, images []string) error {
 	client := dockerCli.Client()
-	ctx := context.Background()
 
 	options := types.ImageRemoveOptions{
 		Force:         opts.force,

cli/command/image/save.go

@@ -26,7 +26,7 @@ func NewSaveCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.images = args
-			return RunSave(dockerCli, opts)
+			return RunSave(cmd.Context(), dockerCli, opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker image save, docker save",
@@ -42,7 +42,7 @@ func NewSaveCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunSave performs a save against the engine based on the specified options
-func RunSave(dockerCli command.Cli, opts saveOptions) error {
+func RunSave(ctx context.Context, dockerCli command.Cli, opts saveOptions) error {
 	if opts.output == "" && dockerCli.Out().IsTerminal() {
 		return errors.New("cowardly refusing to save to a terminal. Use the -o flag or redirect")
 	}
@@ -51,7 +51,7 @@ func RunSave(dockerCli command.Cli, opts saveOptions) error {
 		return errors.Wrap(err, "failed to save image")
 	}
 
-	responseBody, err := dockerCli.Client().ImageSave(context.Background(), opts.images)
+	responseBody, err := dockerCli.Client().ImageSave(ctx, opts.images)
 	if err != nil {
 		return err
 	}

cli/command/image/tag.go

@@ -25,7 +25,7 @@ func NewTagCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.image = args[0]
 			opts.name = args[1]
-			return runTag(dockerCli, opts)
+			return runTag(cmd.Context(), dockerCli, opts)
 		},
 		Annotations: map[string]string{
 			"aliases": "docker image tag, docker tag",
@@ -39,8 +39,6 @@ func NewTagCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runTag(dockerCli command.Cli, opts tagOptions) error {
-	ctx := context.Background()
-
+func runTag(ctx context.Context, dockerCli command.Cli, opts tagOptions) error {
 	return dockerCli.Client().ImageTag(ctx, opts.image, opts.name)
 }

cli/command/image/testdata/inspect-command-success.simple-many.golden

@@ -5,7 +5,6 @@
         "RepoDigests": null,
         "Parent": "",
         "Comment": "",
-        "Created": "",
         "Container": "",
         "ContainerConfig": null,
         "DockerVersion": "",
@@ -29,7 +28,6 @@
         "RepoDigests": null,
         "Parent": "",
         "Comment": "",
-        "Created": "",
         "Container": "",
         "ContainerConfig": null,
         "DockerVersion": "",

cli/command/image/testdata/inspect-command-success.simple.golden

@@ -5,7 +5,6 @@
         "RepoDigests": null,
         "Parent": "",
         "Comment": "",
-        "Created": "",
         "Container": "",
         "ContainerConfig": null,
         "DockerVersion": "",

cli/command/inspect/inspector.go

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

cli/command/manifest/create_list.go

@@ -25,7 +25,7 @@ func newCreateListCommand(dockerCli command.Cli) *cobra.Command {
 		Short: "Create a local manifest list for annotating and pushing to a registry",
 		Args:  cli.RequiresMinArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return createManifestList(dockerCli, args, opts)
+			return createManifestList(cmd.Context(), dockerCli, args, opts)
 		},
 	}
 
@@ -35,7 +35,7 @@ func newCreateListCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func createManifestList(dockerCli command.Cli, args []string, opts createOpts) error {
+func createManifestList(ctx context.Context, dockerCli command.Cli, args []string, opts createOpts) error {
 	newRef := args[0]
 	targetRef, err := normalizeReference(newRef)
 	if err != nil {
@@ -58,7 +58,6 @@ func createManifestList(dockerCli command.Cli, args []string, opts createOpts) e
 		return errors.Errorf("refusing to amend an existing manifest list with no --amend flag")
 	}
 
-	ctx := context.Background()
 	// Now create the local manifest list transaction by looking up the manifest schemas
 	// for the constituent images:
 	manifests := args[1:]

cli/command/manifest/inspect.go

@@ -39,7 +39,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command {
 				opts.list = args[0]
 				opts.ref = args[1]
 			}
-			return runInspect(dockerCli, opts)
+			return runInspect(cmd.Context(), dockerCli, opts)
 		},
 	}
 
@@ -49,7 +49,7 @@ func newInspectCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runInspect(dockerCli command.Cli, opts inspectOptions) error {
+func runInspect(ctx context.Context, dockerCli command.Cli, opts inspectOptions) error {
 	namedRef, err := normalizeReference(opts.ref)
 	if err != nil {
 		return err
@@ -76,7 +76,6 @@ func runInspect(dockerCli command.Cli, opts inspectOptions) error {
 	}
 
 	// Next try a remote manifest
-	ctx := context.Background()
 	registryClient := dockerCli.RegistryClient(opts.insecure)
 	imageManifest, err := registryClient.GetManifest(ctx, namedRef)
 	if err == nil {

cli/command/manifest/push.go

@@ -53,7 +53,7 @@ func newPushListCommand(dockerCli command.Cli) *cobra.Command {
 		Args:  cli.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.target = args[0]
-			return runPush(dockerCli, opts)
+			return runPush(cmd.Context(), dockerCli, opts)
 		},
 	}
 
@@ -63,7 +63,7 @@ func newPushListCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runPush(dockerCli command.Cli, opts pushOpts) error {
+func runPush(ctx context.Context, dockerCli command.Cli, opts pushOpts) error {
 	targetRef, err := normalizeReference(opts.target)
 	if err != nil {
 		return err
@@ -82,7 +82,6 @@ func runPush(dockerCli command.Cli, opts pushOpts) error {
 		return err
 	}
 
-	ctx := context.Background()
 	if err := pushList(ctx, dockerCli, req); err != nil {
 		return err
 	}

cli/command/manifest/rm.go

@@ -1,6 +1,7 @@
 package manifest
 
 import (
+	"context"
 	"strings"
 
 	"github.com/docker/cli/cli"
@@ -15,14 +16,14 @@ func newRmManifestListCommand(dockerCli command.Cli) *cobra.Command {
 		Short: "Delete one or more manifest lists from local storage",
 		Args:  cli.RequiresMinArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return runRm(dockerCli, args)
+			return runRm(cmd.Context(), dockerCli, args)
 		},
 	}
 
 	return cmd
 }
 
-func runRm(dockerCli command.Cli, targets []string) error {
+func runRm(_ context.Context, dockerCli command.Cli, targets []string) error {
 	var errs []string
 	for _, target := range targets {
 		targetRef, refErr := normalizeReference(target)

cli/command/network/connect.go

@@ -36,7 +36,7 @@ func newConnectCommand(dockerCli command.Cli) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			options.network = args[0]
 			options.container = args[1]
-			return runConnect(dockerCli, options)
+			return runConnect(cmd.Context(), dockerCli, options)
 		},
 		ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
 			if len(args) == 0 {
@@ -57,7 +57,7 @@ func newConnectCommand(dockerCli command.Cli) *cobra.Command {
 	return cmd
 }
 
-func runConnect(dockerCli command.Cli, options connectOptions) error {
+func runConnect(ctx context.Context, dockerCli command.Cli, options connectOptions) error {
 	client := dockerCli.Client()
 
 	driverOpts, err := convertDriverOpt(options.driverOpts)
@@ -75,7 +75,7 @@ func runConnect(dockerCli command.Cli, options connectOptions) error {
 		DriverOpts: driverOpts,
 	}
 
-	return client.NetworkConnect(context.Background(), options.network, options.container, epConfig)
+	return client.NetworkConnect(ctx, options.network, options.container, epConfig)
 }
 
 func convertDriverOpt(options []string) (map[string]string, error) {