19.1.1 Build CLI Command

The build CLI command supports a considerably broader flag set than the basic -t and -f covered in general image command usage, and understanding these additional flags directly, progress output control, secret and SSH forwarding, output destination control, and scripting-oriented flags like --iidfile, unlocks capability genuinely needed for more advanced or automated build scenarios.

Controlling build progress output

The --progress flag controls how build output is displayed, useful specifically when the default, condensed output is hiding detail needed to diagnose a build failure:

docker build --progress=plain -t my-api .
docker build --progress=tty -t my-api .

plain mode produces more complete, line-by-line output without the default's collapsing and overwriting behavior, which is generally the more useful mode specifically when troubleshooting a build failure rather than during routine, successful builds where the more compact default is easier to read.

Forwarding secrets and SSH agents into the build

Beyond the basic secret mount syntax covered in dedicated security content, the build command's secret and SSH forwarding flags support several distinct source types:

docker build --secret id=npm_token,src=./token.txt -t my-api .
docker build --secret id=npm_token,env=NPM_TOKEN -t my-api .
docker build --ssh default -t my-api .

The env source variant pulls a secret value directly from an environment variable already present in the shell running the build, rather than requiring it to exist as a file on disk first, which is convenient for CI environments where secrets are typically already injected as environment variables.

Multi-platform builds and platform targeting

docker build --platform=linux/amd64 -t my-api .
docker buildx build --platform=linux/amd64,linux/arm64 -t my-api --push .

Multi-platform output specifically requires docker buildx build rather than the plain docker build command, since producing and assembling a multi-architecture manifest list is a BuildKit-specific capability not available through the legacy builder.

Cache import and export

docker buildx build --cache-from=type=registry,ref=registry.example.com/my-api:cache .
docker buildx build --cache-to=type=registry,ref=registry.example.com/my-api:cache,mode=max --push .

These flags, covered conceptually in dedicated BuildKit caching content, are how a CI pipeline shares build cache across separate, otherwise independent job runs that would each start from an empty cache without this explicit cache persistence mechanism.

Controlling build output destination

The --output flag controls where a build's result actually goes, supporting destinations beyond the default behavior of loading the result into the local image store:

docker buildx build --output type=local,dest=./output .
docker buildx build --output type=tar,dest=./output.tar .
docker buildx build --output type=registry --push .

The local and tar output types are particularly useful for a build whose actual purpose is producing build artifacts, compiled binaries, static site output, rather than a runnable container image at all, extracting directly to the host filesystem without needing a separate step to copy files out of a built image afterward.

Capturing the resulting image ID for scripting

docker build -t my-api . --iidfile image-id.txt
cat image-id.txt

sha256:3f29a8c1d8e2b4f6a9c7d5e8b1f3a6c9d2e5f8b1a4c7d0e3f6a9c2d5e8b1f4a7

Writing the resulting image ID to a file this way is more reliable for scripting than attempting to parse it from the build's own console output, particularly useful for a pipeline step that needs to reference the exact image just built in a subsequent step without depending on fragile text parsing.

Adding labels at build time

docker build --label org.opencontainers.image.revision="$(git rev-parse HEAD)" -t my-api .

This provides an alternative to embedding a LABEL instruction directly in the Dockerfile for a value that genuinely needs to be supplied dynamically at build time rather than fixed in the Dockerfile's own source.

Network mode during the build

docker build --network=host -t my-api .
docker build --network=none -t my-api .

Covered in dedicated build network troubleshooting content, these flags control what networking, if any, build instructions have access to, useful both for resolving certain network-related build issues and for explicitly verifying a build does not depend on network access at all.

Common mistakes

• Not using --progress=plain when the default, condensed output is obscuring the specific detail needed to diagnose a build failure.
• Forgetting that multi-platform output specifically requires docker buildx build rather than the plain, legacy docker build command.
• Attempting to parse a build's resulting image ID from console output rather than using --iidfile for a more reliable, scriptable result.
• Not knowing about the --output flag's local and tar destination types when a build's actual goal is extracting artifacts rather than producing a runnable image.
• Using a build argument or embedded environment variable for a secret rather than the dedicated --secret flag, leaving the value recoverable from layer history.

The build CLI command's flag set extends considerably beyond basic tagging and Dockerfile selection, and fluency with progress control, secret and SSH forwarding, multi-platform and cache flags, output destination control, and scripting-oriented flags like --iidfile unlocks the genuinely advanced build capability needed for production CI pipelines and more sophisticated build scenarios beyond simple, single-image local builds.