From aeccedfe4a10cf739f5b7aa7eb90d64d44a09f75 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Fri, 7 Aug 2026 11:48:39 +0500
Subject: [PATCH] docs: note --health-cmd always uses CMD-SHELL

Runtime health checks go through the image shell, so scratch-based
images need HEALTHCHECK CMD in the Dockerfile instead of --health-cmd.

Fixes #3719

Signed-off-by: Dean Chen <862469039@qq.com>
---
 docs/reference/commandline/container_run.md | 22 +++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/reference/commandline/container_run.md b/docs/reference/commandline/container_run.md
index 1dcc0fd5387b..5b265a43b0f0 100644
--- a/docs/reference/commandline/container_run.md
+++ b/docs/reference/commandline/container_run.md
@@ -604,6 +604,28 @@ $ docker run --pull=never hello-world
 docker: Error response from daemon: No such image: hello-world:latest.
 ```
 
+### <a name="health-cmd"></a> Health checks (--health-cmd)
+
+`--health-cmd` sets a command the daemon runs to decide if the container is
+healthy. Unlike `HEALTHCHECK` in a Dockerfile, which can choose `CMD` or
+`CMD-SHELL`, runtime `--health-cmd` is always executed with `CMD-SHELL`
+(the image's shell, typically `/bin/sh -c`).
+
+That means images without a shell — for example anything `FROM scratch` that
+only has a static binary — cannot use `--health-cmd` unless you also provide a
+shell in the image. For those images, define a `HEALTHCHECK` with the `CMD`
+form in the Dockerfile instead (not `CMD-SHELL`), or bake a shell into a
+minimal base image.
+
+```console
+$ docker run --name=test -d \
+    --health-cmd='stat /etc/passwd || exit 1' \
+    --health-interval=2s \
+    busybox sleep 1d
+$ docker inspect --format='{{.State.Health.Status}}' test
+healthy
+```
+
 ### <a name="env"></a> Set environment variables (-e, --env, --env-file)
 
 ```console