19.1 Image CLI Commands

Image CLI commands cover the full practical command set for building, transferring, inspecting, and cleaning up images, the actual day-to-day commands that turn the conceptual image practices covered elsewhere into concrete, executable actions against a specific image.

Building an image

docker build -t my-api:1.4.2 .
docker build -f Dockerfile.prod -t my-api:1.4.2 .
docker build --target production -t my-api:1.4.2 .
docker build --build-arg NODE_ENV=production -t my-api:1.4.2 .

The -t flag tags the resulting image directly during the build; omitting it produces an untagged image identifiable only by its image ID, generally inconvenient for anything beyond an immediate, throwaway test build.

Pulling and pushing images

docker pull my-api:1.4.2
docker pull registry.example.com/my-api@sha256:3f29a8c1...
docker push registry.example.com/my-api:1.4.2

Pulling by digest rather than tag guarantees retrieval of an exact, specific, immutable content reference, while pushing requires having first authenticated to the target registry through docker login if it requires authentication.

Tagging an image

docker tag my-api:1.4.2 registry.example.com/my-api:1.4.2
docker tag my-api:1.4.2 my-api:latest

Tagging does not duplicate the underlying image content; it creates an additional reference pointing at the same existing image, which means tagging is an essentially instantaneous, local operation regardless of the image's actual size.

Listing and inspecting images

docker images
docker image ls --filter "dangling=true"
docker inspect my-api:1.4.2
docker history my-api:1.4.2 --no-trunc

docker history specifically reveals the layer-by-layer build instruction record, useful for understanding exactly how an image was constructed without needing the original Dockerfile readily available.

Saving and loading images as archive files

docker save my-api:1.4.2 -o my-api.tar
docker load -i my-api.tar

This pair of commands transfers an image as a portable archive file without going through a registry at all, useful for air-gapped environments or transferring an image directly between two hosts with no shared registry access between them.

Exporting and importing a container's filesystem

docker export my-api-container -o snapshot.tar
docker import snapshot.tar my-api:snapshot

Distinct from save/load, which preserves an image's full layer history and metadata, export/import flattens a container's current filesystem state into a single, new layer with no preserved history, useful for a specific kind of filesystem snapshot but not a general substitute for proper image building.

Removing images

docker rmi my-api:1.4.2
docker image prune
docker image prune -a

docker rmi my-api:1.4.2 --force

docker image prune without -a removes only dangling (untagged) images; adding -a removes every image not currently referenced by any running container, a considerably more aggressive cleanup worth using deliberately rather than reflexively.

Verifying an image's digest

docker inspect my-api:1.4.2 --format '{{index .RepoDigests 0}}'

This is the practical command for retrieving an image's actual content digest, the value needed for digest-based pinning and deployment references covered in dedicated production practice content.

Checking image disk usage

docker system df
docker system df -v

The verbose flag breaks down disk usage per individual image, container, and volume rather than only the aggregate totals the non-verbose form provides.

Building with no cache

docker build --no-cache -t my-api .
docker build --pull --no-cache -t my-api .

Combining both flags forces a genuinely fresh build from a freshly pulled base image, the most thorough way to rule out stale caching as an explanation for unexpected build behavior.

Common mistakes

• Omitting -t during a build, producing an untagged image that is inconvenient to reference for anything beyond an immediate test.
• Confusing save/load with export/import, using the latter when full layer history preservation was actually needed.
• Running docker image prune -a reflexively as routine cleanup without considering it removes every currently unused image, not just dangling, untagged ones.
• Not retrieving an image's actual digest directly when a deployment process specifically needs to pin by digest rather than mutable tag.
• Relying on the non-verbose docker system df output when investigating which specific image is responsible for disk usage, missing the per-image breakdown the verbose flag provides.

Image CLI commands cover building, transferring, inspecting, and cleaning up images through a focused, consistent set of commands, and fluency with the specific distinctions between similar-looking pairs, save versus export, tag versus rebuild, dangling versus all-unused pruning, is what turns conceptual image management knowledge into confident, correct day-to-day command usage.