Guide · Docker
Docker autocomplete in zsh on the Mac: containers and images at the cursor
Last checked 19 November 2026
In short: type docker exec -it and Termhint's popup lists your running containers, each with its image and status. docker run lists your images with their size. The names come from the Docker engine on your Mac, a moment after the other suggestions; Termhint never runs docker to get them.
What you type, what the popup lists
| You type | The popup lists |
|---|---|
docker exec, logs, stop, restart, kill, top, stats, port, pause | Running containers |
docker start, rm | All containers, stopped ones too |
docker inspect | All containers and images |
docker run, create, rmi, save, history | Images |
docker container …, docker image … | The same lists for most long forms (docker container inspect lists running containers) |
Each container is listed by name, with its image and status as the description. Each image is listed as repository:tag with its short ID and size; an image without a tag is listed by its short ID and reads "Untagged".
An example
With two containers, api and postgres, running:
$ docker exec -it
api example/api:latest · Up 2 hours
postgres postgres:16 · Up 2 hours
$ docker run
example/api:latest 3f2a9c1d7b4e · 212 MB
postgres:16 8e1b5a0c2d6f · 438 MB
Subcommands and options (docker run - offers -it, --rm, -p and the rest, each described) come from the Docker completion spec at once, like every zsh autocomplete suggestion.
Why they arrive a moment later
The engine can be slow to answer, or not running at all, and a keystroke should never wait for it. So the popup opens with what it already has, and Termhint asks the engine in the background with a one-second limit. When the answer differs from what is shown, the popup fills in. The lists are kept and asked again in the background when they are more than two seconds old. With the engine stopped, the popup lists no containers or images and everything else works as usual.
Never by running docker
Fig's Docker completions ran docker ps and docker image ls. Termhint asks the Docker engine API directly over the Unix socket of your current docker context (set with docker context use), or else the usual local sockets. DOCKER_HOST and DOCKER_CONTEXT are not read. In order:
- the socket of your current
docker context, read from~/.docker; - otherwise the first of
/var/run/docker.sockand the sockets of Docker Desktop (~/.docker/run), OrbStack (~/.orbstack/run) and Colima (~/.colima/default) that exists.
Only a socket owned by you or by root is used: another user's socket could answer anything. A context that points to another machine (ssh://, tcp://) gets no container or image suggestions, so the popup never shows a different engine's objects. Container and image names stay in memory on your Mac; the ranking Termhint learns keeps only command, subcommand and option names, never arguments.
Where it works
Termhint is a Mac app (macOS 14 or later, Apple silicon) for zsh. The popup shows in the terminals on the terminals page, and inside tmux, its split panes too. The same popup lists git branches, ssh hosts and Makefile targets.
FAQ
Does Termhint run the docker command?
No. It asks the Docker engine directly over the Unix socket of your current docker context (set with docker context use), or else the usual local sockets, and only a socket that belongs to you or to root. DOCKER_HOST and DOCKER_CONTEXT are not read.
Why do containers show up a moment after the other suggestions?
The engine can be slow or stopped, so a keystroke never waits for it. The popup shows the rest at once and adds containers and images when the engine answers, within a second. After that they are kept and refreshed in the background.
Does it work with Docker Desktop, OrbStack and Colima?
Yes. Termhint uses the socket of your current docker context, or else the usual sockets of Docker Desktop, OrbStack, Colima and /var/run/docker.sock.
What about a remote docker context?
A context that points at another machine (ssh:// or tcp://) gets no container or image suggestions. Subcommands and options still complete.
What it costs
Every feature works for 7 days with no account and no card. After that, a one-time license: $11.99 for 1 Mac, $19.99 for 3, $29.99 for 5, plus VAT or sales tax where it applies (pricing).