Audit Docker Targets with docker context ls

Half of all "why did that delete the wrong containers" stories start with a forgotten context, and docker context ls is the ten-second check. You will see which Docker daemons the CLI can target, spot the active one 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.

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. Here, default points at the local Unix socket. Your table can contain more contexts, such as staging or production, with different descriptions and endpoints.

2. Understand what the active row means

The default context is commonly backed by the DOCKER_HOST setting, which is why the local description reads "Current DOCKER_HOST based configuration".

The active context can also be changed 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

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 prints one context name per line. It suits a menu, a validation loop or a shell pipeline, but it deliberately omits the endpoint and the active marker.

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

When another program needs structured records, use the documented --format json form:

$ 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, because 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 a script will use it, and quote it so the shell does not interpret the braces or spaces.

6. Handle errors before acting

The table has an ERROR column, so a row can be listed while still showing a problem with its configuration or endpoint.

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 works best 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"