Docker Syntax CLI Images

docker-syntax-cli-images

Quick Reference

Image Lifecycle Commands

System Management Commands

Critical Warnings

NEVER run docker system prune -a --volumes on production systems without first running docker system df -- it removes ALL unused volumes including database data.

NEVER use docker build (legacy) for new projects -- ALWAYS use docker buildx build which is the default BuildKit-based builder since Docker Engine 23+.

NEVER push images without verifying the tag -- docker push myapp pushes ALL tags of that repository. ALWAYS specify the exact tag: docker push myapp:v1.

ALWAYS use --platform when building for a different architecture -- omitting it silently builds for the host platform, causing exec format error at runtime on the target.

ALWAYS run docker system df before any cleanup operation to understand what is consuming disk space.

Buildx Build Flag Reference

Core Build Flags

Output Flags

Output types: docker (local), registry (push), local (filesystem), tar, oci, image.

Multi-Platform Flags

ALWAYS use --push or -o (not --load) when building for multiple platforms -- --load only supports single-platform images.

Cache Flags

Cache types: registry, local, inline, gha (GitHub Actions), s3, azblob.

Security & Secrets Flags

Attestation Flags

Buildx Builder Management

# Create a new builder instance
docker buildx create --name mybuilder --use

# List all builders
docker buildx ls

# Inspect current builder
docker buildx inspect

# Switch to a builder
docker buildx use mybuilder

# Remove a builder
docker buildx rm mybuilder

ALWAYS create a dedicated builder for multi-platform builds -- the default builder does not support multi-platform output.

Image Filter Cheat Sheet

docker images --filter

Image Format Placeholders

# Compact image list
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

# JSON output (one per line)
docker images --format json

# Only IDs for scripting
docker images -q

# Remove all dangling images
docker rmi $(docker images -q -f dangling=true)

Disk Cleanup Strategy

ALWAYS follow this order -- from safest to most aggressive:

1. Assess -- docker system df -v
2. Containers -- docker container prune -f
3. Dangling images -- docker image prune -f
4. All unused images -- docker image prune -a -f
5. Build cache -- docker builder prune -f
6. Volumes -- docker volume ls -f dangling=true then docker volume prune -f
7. Nuclear -- docker system prune -a --volumes -f

What Each Prune Removes

Prune Filter Flags

Decision Tree: Which Cleanup Command?

Need to free disk space?
├── Know what's using space? → docker system df -v
├── Just dangling/untagged images? → docker image prune -f
├── All unused images? → docker image prune -a -f
├── Stopped containers? → docker container prune -f
├── Build cache growing? → docker builder prune -f
├── Unused volumes? → docker volume prune -f (CHECK FIRST!)
└── Everything unused? → docker system prune -a --volumes -f (DANGEROUS on prod)

Need to transfer images offline?
├── Full image with layers + tags + history → docker save / docker load
├── Container filesystem snapshot (no metadata) → docker export / docker import
└── Multi-platform manifest → docker manifest create + push

Need multi-platform builds?
├── Single platform, local use → docker buildx build --platform linux/amd64 --load .
├── Multiple platforms, push to registry → docker buildx build --platform linux/amd64,linux/arm64 --push .
└── Need a builder first? → docker buildx create --name mp --use

System Information Commands

docker system df

docker system df              # Summary: images, containers, volumes, build cache
docker system df -v           # Verbose per-resource breakdown
docker system df --format "table {{.Type}}\t{{.TotalCount}}\t{{.Size}}\t{{.Reclaimable}}"

docker info

docker info                                    # Full system information
docker info --format '{{.ServerVersion}}'      # Server version only
docker info --format '{{.Driver}}'             # Storage driver
docker info --format '{{json .Plugins}}'       # Available plugins

docker version

docker version                                 # Client + server versions
docker version --format '{{.Server.Version}}'  # Server version only
docker version --format json                   # JSON output

docker context

docker context ls                                                    # List all contexts
docker context create remote --docker "host=ssh://user@remote-host"  # Create SSH context
docker context use remote                                            # Switch to context
docker context use default                                           # Switch back
docker context inspect remote                                        # Show details
docker context rm remote                                             # Remove context

Reference Links

• references/commands.md -- Complete image and system command reference with all flags
• references/examples.md -- Image management workflows and cleanup scripts
• references/anti-patterns.md -- Common image management mistakes and how to avoid them

Official Sources

• https://docs.docker.com/reference/cli/docker/image/
• https://docs.docker.com/reference/cli/docker/buildx/build/
• https://docs.docker.com/reference/cli/docker/image/ls/
• https://docs.docker.com/reference/cli/docker/system/
• https://docs.docker.com/reference/cli/docker/system/prune/
• https://docs.docker.com/reference/cli/docker/system/df/