enhancement: show when context is overridden by "DOCKER_HOST" or other options
Nobody has claimed this yet.
- 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)currentContextfield 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
Serversection, however, theServeritself 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 showfor 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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