docker / docker/cli

enhancement: show when context is overridden by "DOCKER_HOST" or other options

Open
#6,151 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

kind/feature status/1-design-review
Dominant language
Go
Stars
6.1k
Forks
2.2k
Avg merge
1d 15h
Merged PRs (30d)
43

Description

Description

The Docker CLI defaults to using a local daemon through a unix-socket (Linux, macOS) or named pipe (Windows), but it can be configured to use a different connection, which can be a remote machine.

There's various ways to configure the CLI; (also see DockerCli.CurrentContext);

  • DOCKER_HOST (takes precedence over context)
  • --host / -H (configures the connection to use)
  • DOCKER_CONTEXT (configure the context, which is used to configure the connection)
  • --context (configure the context, which is used to configure the connection)
  • currentContext field in ~/.docker/config.json (configures the default context to configure the connection)
  • In rootless-mode, other env-vars may be involved for the default socket path.

Some of these options may not be very visible; we have some warnings when performing docker context operations to inform the user that DOCKER_HOST is set (and overrides the selected context);
https://github.com/docker/cli/blob/1d768f8983f90abaf7065c76102312eb2ffc42a4/cli/command/context/list.go#L110-L113
https://github.com/docker/cli/blob/1d768f8983f90abaf7065c76102312eb2ffc42a4/cli/command/context/use.go#L52-L55

However, other places may not show this information. Most notably docker version and docker info;

Current context (in the CLI's config) is desktop-linux;

cat ~/.docker/config.json | jq .currentContext
"desktop-linux"

However, docker version shows that the default context is used;

docker version
Client:
 Version:           28.3.0-rc.1
 API version:       1.42 (downgraded from 1.51)
 Go version:        go1.24.4
 Git commit:        f53bb88
 Built:             Fri Jun 13 18:25:06 2025
 OS/Arch:           darwin/arm64
 Context:           default

And docker info does the same;

docker info | head -n 5
Client:
 Version:    28.3.0-rc.1
 Context:    default
 Debug Mode: false
 Plugins:

In the above situation, the reason was that DOCKER_HOST was set in the current shell;

env | grep DOCKER
DOCKER_HOST=ssh://swarm-test-01/var/run/docker.sock

Improvement: make active connection more visible

⚠️ This is just a draft; detailed design still needed

1. Include "Docker Host" in docker version and docker info

We can include the active host in output of docker version and docker info;

docker version
Client:
 Version:           28.3.0-rc.1
 API version:       1.42 (downgraded from 1.51)
 Go version:        go1.24.4
 Git commit:        f53bb88
 Built:             Fri Jun 13 18:25:06 2025
 OS/Arch:           darwin/arm64
 Context:           default
 Docker Host:       ssh://swarm-test-01/var/run/docker.sock
docker info | head -n 5
Client:
 Version:     28.3.0-rc.1
 Context:     default
 Docker Host: ssh://swarm-test-01/var/run/docker.sock
 Debug Mode:  false
  • ☝️ alternatively, we could include this in the Server section, however, the Server itself may be serving the API on multiple "hosts" (e.g. both on a socket AND through tcp); https://github.com/moby/moby/pull/43459
2. Show what determined the active context

We can show "why" the given context is used, e.g.;

 Context:           default (context disabled because DOCKER_HOST is set)
 Context:           desktop-linux (from DOCKER_CONTEXT)
 Context:           desktop-linux (from "~/.docker/config.json`)

⚠️ the above output may be used by users in scripting (docker version | grep 'Context:');

  • Generally, users should use docker context show for this, but it may be a breaking change
  • When formatting, we should make this a separate part of the template so that docker version --format '{{.Client.Context}}' only shows the context name (same for `docker info --format``)
3. Show what determined the active "host" connection

Similar to the above; show where the connection string came from;

 Docker Host:       ssh://swarm-test-01/var/run/docker.sock (from DOCKER_HOST)

❓ should we also show if this comes from the active context? (when not overridden by DOCKER_HOST)? Or is that just "noise"?

 Docker Host:       ssh://swarm-test-01/var/run/docker.sock (from "desktop-linux" context)

or

 Docker Host:       ssh://swarm-test-01/var/run/docker.sock (from current context)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading cli/command/cli.go and the warning logic in cli/command/context/list.go and cli/command/context/use.go. Compare how docker version and docker info currently report Context, then define the output and formatting behavior for overridden contexts and active hosts. Done means the design resolves the open alternatives without breaking formatted output or scripting expectations.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, go
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.