Audit Docker Targets Safely with docker context ls

You will use docker context ls to see which Docker daemon the CLI can target, identify the active context, and produce output that is safe for scripts. Allow about ten minutes. The examples use Docker CLI 29.8.1 from docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble, installed on this machine.

This command only lists client-side context information. It does not create, remove or switch a context, and it normally needs no elevated privileges. The endpoint may still be remote or protected, so treat its names and addresses as operationally sensitive.

1. List every available context

Run the command without options:

$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT               ERROR
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock

The table has one row per context. An asterisk after the name marks the context currently selected for ordinary Docker commands. In this installation, default points at the local Unix socket. Your table can contain additional contexts such as staging or production, with different descriptions and endpoints.

Checkpoint: confirm the asterisk is beside the daemon you expect before running a command that creates, removes or changes Docker resources. A context name is not proof that the endpoint is local.

2. Understand what the active row means

The default context is commonly backed by the DOCKER_HOST setting, which is why the description in the local output says "Current DOCKER_HOST based configuration". The active context can also be affected by the DOCKER_CONTEXT environment variable or a command-wide --context option. Docker documents DOCKER_CONTEXT as an override for both DOCKER_HOST and the default selected with docker context use.

Check for an environment override before trusting a surprising result:

$ printf 'DOCKER_CONTEXT=%s
' "${DOCKER_CONTEXT:-<unset>}"
$ printf 'DOCKER_HOST=%s
' "${DOCKER_HOST:-<unset>}"
$ docker context ls

Do not assume that changing a shell variable is harmless. A value such as DOCKER_CONTEXT=production can redirect later Docker commands in that shell. If you only need a different target for one operation, use Docker's global --context option on that operation and inspect the target first.

3. Get only context names

Use --quiet, also written -q, when a script needs names rather than a human-readable table:

$ docker context ls --quiet
default

This output contains one context name per line. It is useful for a menu, a validation loop or a shell pipeline, but it deliberately omits the endpoint and the active marker. Do not use it alone for a deployment safety check: a name-only list cannot tell you where a context connects.

For example, fail early if a required context is missing:

if docker context ls --quiet | grep -Fxq 'staging'; then
    printf '%s
' 'staging context is available'
else
    printf '%s
' 'staging context is missing' >&2
    exit 1
fi

The check only confirms that the client knows a context with that name. It does not authenticate to the daemon or prove that the endpoint is reachable.

4. Produce JSON for tooling

Use the documented --format json form when another program needs structured records:

$ docker context ls --format json
{"Current":true,"Description":"Current DOCKER_HOST based configuration","DockerEndpoint":"unix:///var/run/docker.sock","Error":"","Name":"default"}

On this CLI, the JSON object includes Current, Description, DockerEndpoint, Error and Name. Parse it as JSON rather than splitting the table on spaces. Descriptions can contain spaces, and an endpoint or error field can be empty.

For a quick shell check, pass the stream to a JSON parser if one is installed:

docker context ls --format json | jq -r 'select(.Current) | [.Name, .DockerEndpoint, .Error] | @tsv'

The Docker command remains read-only here. The separate jq command is optional and is not supplied by Docker.

5. Use a Go template for a small report

The other --format form accepts a Go template. This local check prints the fields in a compact, reviewable layout:

$ docker context ls --format '{{.Name}}|{{.Current}}|{{.Description}}|{{.DockerEndpoint}}|{{.Error}}'
default|true|Current DOCKER_HOST based configuration|unix:///var/run/docker.sock|

The fields above are the ones exposed by the installed command's JSON output. Keep the template simple when it will be used in a script, and quote it so the shell does not interpret the braces or spaces. If you need column headings, the manual also supports table TEMPLATE; otherwise the plain template emits only the rendered rows.

6. Handle errors before acting

The table has an ERROR column. A row can therefore be listed while still showing a problem with its configuration or endpoint. Treat a non-empty error as a reason to stop and investigate, not as permission to try a destructive Docker command anyway.

docker context ls --format json | jq -e '
    (.Error == "") and (.Current == true)
' >/dev/null

This example succeeds only when every JSON record it receives has no error and is current. It is most useful when there is one expected current context; for more complex checks, select the named record and compare its endpoint with an approved value. Do not paste real production endpoints or credentials into tickets or shell history unnecessarily.

If the list itself fails, capture the status immediately and read the diagnostic:

docker context ls
status=$?
printf 'docker context ls exited with status %s
' "$status" >&2
exit "$status"

Use ordinary user privileges first. Only investigate access with sudo if the Docker installation or socket permissions explicitly require it; elevated privileges can make a command appear to work while hiding the permission problem that a service account will encounter.