diff --git a/docs/reference/commandline/cli.md b/docs/reference/commandline/cli.md index e73580f1fc90..dbfe2a5e4193 100644 --- a/docs/reference/commandline/cli.md +++ b/docs/reference/commandline/cli.md @@ -10,105 +10,8 @@ aliases: - /engine/reference/commandline/engine_update/ --- - - -# docker - -To list available commands, either run `docker` with no parameters -or execute `docker help`: - - -The base command for the Docker CLI. - -### Subcommands - -| Name | Description | -|:------------------------------|:------------------------------------------------------------------------------| -| [`attach`](attach.md) | Attach local standard input, output, and error streams to a running container | -| [`build`](build.md) | Build an image from a Dockerfile | -| [`builder`](builder.md) | Manage builds | -| [`checkpoint`](checkpoint.md) | Manage checkpoints | -| [`commit`](commit.md) | Create a new image from a container's changes | -| [`config`](config.md) | Manage Swarm configs | -| [`container`](container.md) | Manage containers | -| [`context`](context.md) | Manage contexts | -| [`cp`](cp.md) | Copy files/folders between a container and the local filesystem | -| [`create`](create.md) | Create a new container | -| [`diff`](diff.md) | Inspect changes to files or directories on a container's filesystem | -| [`events`](events.md) | Get real time events from the server | -| [`exec`](exec.md) | Execute a command in a running container | -| [`export`](export.md) | Export a container's filesystem as a tar archive | -| [`history`](history.md) | Show the history of an image | -| [`image`](image.md) | Manage images | -| [`images`](images.md) | List images | -| [`import`](import.md) | Import the contents from a tarball to create a filesystem image | -| [`info`](info.md) | Display system-wide information | -| [`inspect`](inspect.md) | Return low-level information on Docker objects | -| [`kill`](kill.md) | Kill one or more running containers | -| [`load`](load.md) | Load an image from a tar archive or STDIN | -| [`login`](login.md) | Log in to a registry | -| [`logout`](logout.md) | Log out from a registry | -| [`logs`](logs.md) | Fetch the logs of a container | -| [`manifest`](manifest.md) | Manage Docker image manifests and manifest lists | -| [`network`](network.md) | Manage networks | -| [`node`](node.md) | Manage Swarm nodes | -| [`pause`](pause.md) | Pause all processes within one or more containers | -| [`plugin`](plugin.md) | Manage plugins | -| [`port`](port.md) | List port mappings or a specific mapping for the container | -| [`ps`](ps.md) | List containers | -| [`pull`](pull.md) | Download an image from a registry | -| [`push`](push.md) | Upload an image to a registry | -| [`rename`](rename.md) | Rename a container | -| [`restart`](restart.md) | Restart one or more containers | -| [`rm`](rm.md) | Remove one or more containers | -| [`rmi`](rmi.md) | Remove one or more images | -| [`run`](run.md) | Create and run a new container from an image | -| [`save`](save.md) | Save one or more images to a tar archive (streamed to STDOUT by default) | -| [`search`](search.md) | Search Docker Hub for images | -| [`secret`](secret.md) | Manage Swarm secrets | -| [`service`](service.md) | Manage Swarm services | -| [`stack`](stack.md) | Manage Swarm stacks | -| [`start`](start.md) | Start one or more stopped containers | -| [`stats`](stats.md) | Display a live stream of container(s) resource usage statistics | -| [`stop`](stop.md) | Stop one or more running containers | -| [`swarm`](swarm.md) | Manage Swarm | -| [`system`](system.md) | Manage Docker | -| [`tag`](tag.md) | Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE | -| [`top`](top.md) | Display the running processes of a container | -| [`trust`](trust.md) | Manage trust on Docker images | -| [`unpause`](unpause.md) | Unpause all processes within one or more containers | -| [`update`](update.md) | Update configuration of one or more containers | -| [`version`](version.md) | Show the Docker version information | -| [`volume`](volume.md) | Manage volumes | -| [`wait`](wait.md) | Block until one or more containers stop, then print their exit codes | - - -### Options - -| Name | Type | Default | Description | -|:---------------------------------|:---------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| -| `--config` | `string` | `/root/.docker` | Location of client config files | -| `-c`, `--context` | `string` | | Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with `docker context use`) | -| `-D`, `--debug` | | | Enable debug mode | -| [`-H`](#host), [`--host`](#host) | `list` | | Daemon socket to connect to | -| `-l`, `--log-level` | `string` | `info` | Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`) | -| `--tls` | | | Use TLS; implied by --tlsverify | -| `--tlscacert` | `string` | `/root/.docker/ca.pem` | Trust certs signed only by this CA | -| `--tlscert` | `string` | `/root/.docker/cert.pem` | Path to TLS certificate file | -| `--tlskey` | `string` | `/root/.docker/key.pem` | Path to TLS key file | -| `--tlsverify` | | | Use TLS and verify the remote | - - - - -## Description +The base command for the Docker CLI is `docker`. For information about the +available flags and subcommands, refer to the [CLI reference](docker.md) Depending on your Docker system configuration, you may be required to preface each `docker` command with `sudo`. To avoid having to use `sudo` with the @@ -124,7 +27,7 @@ The following list of environment variables are supported by the `docker` comman line: | Variable | Description | -|:------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DOCKER_API_VERSION` | Override the negotiated API version to use for debugging (e.g. `1.19`) | | `DOCKER_CERT_PATH` | Location of your authentication keys. This variable is used both by the `docker` CLI and the [`dockerd` daemon](dockerd.md) | | `DOCKER_CONFIG` | The location of your client configuration files. | @@ -136,7 +39,7 @@ line: | `DOCKER_HOST` | Daemon socket to connect to. | | `DOCKER_TLS` | Enable TLS for connections made by the `docker` CLI (equivalent of the `--tls` command-line option). Set to a non-empty value to enable TLS. Note that TLS is enabled automatically if any of the other TLS options are set. | | `DOCKER_TLS_VERIFY` | When set Docker uses TLS and verifies the remote. This variable is used both by the `docker` CLI and the [`dockerd` daemon](dockerd.md) | -| `BUILDKIT_PROGRESS` | Set type of progress output (`auto`, `plain`, `tty`) when [building](build.md) with [BuildKit backend](https://docs.docker.com/build/buildkit/). Use plain to show container output (default `auto`). | +| `BUILDKIT_PROGRESS` | Set type of progress output (`auto`, `plain`, `tty`) when [building](image_build.md) with [BuildKit backend](https://docs.docker.com/build/buildkit/). Use plain to show container output (default `auto`). | Because Docker is developed using Go, you can also use any environment variables used by the Go runtime. In particular, you may find these useful: @@ -215,15 +118,15 @@ if no `--format` flag is provided. | Property | Description | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `configFormat` | Custom default format for `docker config ls` output. See [`docker config ls`](config_ls.md#format) for a list of supported formatting directives. | -| `imagesFormat` | Custom default format for `docker images` / `docker image ls` output. See [`docker images`](images.md#format) for a list of supported formatting directives. | +| `imagesFormat` | Custom default format for `docker images` / `docker image ls` output. See [`docker images`](image_ls.md#format) for a list of supported formatting directives. | | `networksFormat` | Custom default format for `docker network ls` output. See [`docker network ls`](network_ls.md#format) for a list of supported formatting directives. | | `nodesFormat` | Custom default format for `docker node ls` output. See [`docker node ls`](node_ls.md#format) for a list of supported formatting directives. | | `pluginsFormat` | Custom default format for `docker plugin ls` output. See [`docker plugin ls`](plugin_ls.md#format) for a list of supported formatting directives. | -| `psFormat` | Custom default format for `docker ps` / `docker container ps` output. See [`docker ps`](ps.md#format) for a list of supported formatting directives. | +| `psFormat` | Custom default format for `docker ps` / `docker container ps` output. See [`docker ps`](container_ls.md#format) for a list of supported formatting directives. | | `secretFormat` | Custom default format for `docker secret ls` output. See [`docker secret ls`](secret_ls.md#format) for a list of supported formatting directives. | | `serviceInspectFormat` | Custom default format for `docker service inspect` output. See [`docker service inspect`](service_inspect.md#format) for a list of supported formatting directives. | | `servicesFormat` | Custom default format for `docker service ls` output. See [`docker service ls`](service_ls.md#format) for a list of supported formatting directives. | -| `statsFormat` | Custom default format for `docker stats` output. See [`docker stats`](stats.md#format) for a list of supported formatting directives. | +| `statsFormat` | Custom default format for `docker stats` output. See [`docker stats`](container_stats.md#format) for a list of supported formatting directives. | | `tasksFormat` | Custom default format for `docker stack ps` output. See [`docker stack ps`](stack_ps.md#format) for a list of supported formatting directives. | | `volumesFormat` | Custom default format for `docker volume ls` output. See [`docker volume ls`](volume_ls.md#format) for a list of supported formatting directives. | diff --git a/docs/reference/commandline/container_run.md b/docs/reference/commandline/container_run.md index aca38eaf9bf6..6d578de7ed14 100644 --- a/docs/reference/commandline/container_run.md +++ b/docs/reference/commandline/container_run.md @@ -932,7 +932,7 @@ $ cat somefile | docker run -i -a stdin mybuilder dobuild > Linux: it ignores any signal with the default action. So, the process > doesn't terminate on `SIGINT` or `SIGTERM` unless it's coded to do so. -See also [the `docker cp` command](cp.md). +See also [the `docker cp` command](container_cp.md). ### Keep STDIN open (-i, --interactive) @@ -1097,8 +1097,8 @@ This runs the `redis` container with a restart policy of **always**. If the container exits, Docker restarts it. When a restart policy is active on a container, it shows as either `Up` or -`Restarting` in [`docker ps`](ps.md). It can also be useful to use [`docker -events`](events.md) to see the restart policy in effect. +`Restarting` in [`docker ps`](container_ls.md). It can also be useful to use +[`docker events`](system_events.md) to see the restart policy in effect. An increasing delay (double the previous delay, starting at 100 milliseconds) is added before each restart to prevent flooding the server. This means the @@ -1129,8 +1129,8 @@ restart limit is only valid for the **on-failure** policy. #### Inspect container restarts The number of (attempted) restarts for a container can be obtained using the -[`docker inspect`](commandline/inspect.md) command. For example, to get the -number of restarts for container "my-container"; +[`docker inspect`](inspect.md) command. For example, to get the number of +restarts for container "my-container"; ```console $ docker inspect -f "{{ .RestartCount }}" my-container diff --git a/docs/reference/commandline/docker.md b/docs/reference/commandline/docker.md new file mode 100644 index 000000000000..288afdf8abff --- /dev/null +++ b/docs/reference/commandline/docker.md @@ -0,0 +1,86 @@ +# docker + + +The base command for the Docker CLI. + +### Subcommands + +| Name | Description | +|:------------------------------|:------------------------------------------------------------------------------| +| [`attach`](attach.md) | Attach local standard input, output, and error streams to a running container | +| [`build`](build.md) | Build an image from a Dockerfile | +| [`builder`](builder.md) | Manage builds | +| [`checkpoint`](checkpoint.md) | Manage checkpoints | +| [`commit`](commit.md) | Create a new image from a container's changes | +| [`config`](config.md) | Manage Swarm configs | +| [`container`](container.md) | Manage containers | +| [`context`](context.md) | Manage contexts | +| [`cp`](cp.md) | Copy files/folders between a container and the local filesystem | +| [`create`](create.md) | Create a new container | +| [`diff`](diff.md) | Inspect changes to files or directories on a container's filesystem | +| [`events`](events.md) | Get real time events from the server | +| [`exec`](exec.md) | Execute a command in a running container | +| [`export`](export.md) | Export a container's filesystem as a tar archive | +| [`history`](history.md) | Show the history of an image | +| [`image`](image.md) | Manage images | +| [`images`](images.md) | List images | +| [`import`](import.md) | Import the contents from a tarball to create a filesystem image | +| [`info`](info.md) | Display system-wide information | +| [`inspect`](inspect.md) | Return low-level information on Docker objects | +| [`kill`](kill.md) | Kill one or more running containers | +| [`load`](load.md) | Load an image from a tar archive or STDIN | +| [`login`](login.md) | Log in to a registry | +| [`logout`](logout.md) | Log out from a registry | +| [`logs`](logs.md) | Fetch the logs of a container | +| [`manifest`](manifest.md) | Manage Docker image manifests and manifest lists | +| [`network`](network.md) | Manage networks | +| [`node`](node.md) | Manage Swarm nodes | +| [`pause`](pause.md) | Pause all processes within one or more containers | +| [`plugin`](plugin.md) | Manage plugins | +| [`port`](port.md) | List port mappings or a specific mapping for the container | +| [`ps`](ps.md) | List containers | +| [`pull`](pull.md) | Download an image from a registry | +| [`push`](push.md) | Upload an image to a registry | +| [`rename`](rename.md) | Rename a container | +| [`restart`](restart.md) | Restart one or more containers | +| [`rm`](rm.md) | Remove one or more containers | +| [`rmi`](rmi.md) | Remove one or more images | +| [`run`](run.md) | Create and run a new container from an image | +| [`save`](save.md) | Save one or more images to a tar archive (streamed to STDOUT by default) | +| [`search`](search.md) | Search Docker Hub for images | +| [`secret`](secret.md) | Manage Swarm secrets | +| [`service`](service.md) | Manage Swarm services | +| [`stack`](stack.md) | Manage Swarm stacks | +| [`start`](start.md) | Start one or more stopped containers | +| [`stats`](stats.md) | Display a live stream of container(s) resource usage statistics | +| [`stop`](stop.md) | Stop one or more running containers | +| [`swarm`](swarm.md) | Manage Swarm | +| [`system`](system.md) | Manage Docker | +| [`tag`](tag.md) | Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE | +| [`top`](top.md) | Display the running processes of a container | +| [`trust`](trust.md) | Manage trust on Docker images | +| [`unpause`](unpause.md) | Unpause all processes within one or more containers | +| [`update`](update.md) | Update configuration of one or more containers | +| [`version`](version.md) | Show the Docker version information | +| [`volume`](volume.md) | Manage volumes | +| [`wait`](wait.md) | Block until one or more containers stop, then print their exit codes | + + +### Options + +| Name | Type | Default | Description | +|:--------------------|:---------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| +| `--config` | `string` | `/root/.docker` | Location of client config files | +| `-c`, `--context` | `string` | | Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with `docker context use`) | +| `-D`, `--debug` | | | Enable debug mode | +| `-H`, `--host` | `list` | | Daemon socket to connect to | +| `-l`, `--log-level` | `string` | `info` | Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`) | +| `--tls` | | | Use TLS; implied by --tlsverify | +| `--tlscacert` | `string` | `/root/.docker/ca.pem` | Trust certs signed only by this CA | +| `--tlscert` | `string` | `/root/.docker/cert.pem` | Path to TLS certificate file | +| `--tlskey` | `string` | `/root/.docker/key.pem` | Path to TLS key file | +| `--tlsverify` | | | Use TLS and verify the remote | + + + + diff --git a/docs/reference/commandline/image_build.md b/docs/reference/commandline/image_build.md index 61f7f384a948..e3bddbaaeaf6 100644 --- a/docs/reference/commandline/image_build.md +++ b/docs/reference/commandline/image_build.md @@ -321,7 +321,7 @@ $ docker build -t vieux/apache:2.0 . This examples builds in the same way as the previous example, but it then tags the resulting image. The repository name will be `vieux/apache` and the tag `2.0`. -[Read more about valid tags](tag.md). +[Read more about valid tags](image_tag.md). You can apply multiple tags to an image. For example, you can apply the `latest` tag to a newly built image and add another tag that references a specific diff --git a/docs/reference/commandline/image_pull.md b/docs/reference/commandline/image_pull.md index ada165558c2f..081b9261f820 100644 --- a/docs/reference/commandline/image_pull.md +++ b/docs/reference/commandline/image_pull.md @@ -81,7 +81,7 @@ Status: Downloaded newer image for debian:bookworm docker.io/library/debian:bookworm ``` -To see which images are present locally, use the [`docker images`](images.md) +To see which images are present locally, use the [`docker images`](image_ls.md) command: ```console diff --git a/docs/reference/commandline/image_push.md b/docs/reference/commandline/image_push.md index a2c83dbe1000..5cc2f3c1b08a 100644 --- a/docs/reference/commandline/image_push.md +++ b/docs/reference/commandline/image_push.md @@ -23,8 +23,8 @@ Upload an image to a registry Use `docker image push` to share your images to the [Docker Hub](https://hub.docker.com) registry or to a self-hosted one. -Refer to the [`docker image tag`](tag.md) reference for more information about valid -image and tag names. +Refer to the [`docker image tag`](image_tag.md) reference for more information +about valid image and tag names. Killing the `docker image push` process, for example by pressing `CTRL-c` while it is running in a terminal, terminates the push operation. @@ -46,9 +46,9 @@ this via the `--max-concurrent-uploads` daemon option. See the ### Push a new image to a registry -First save the new image by finding the container ID (using [`docker container ls`](ps.md)) -and then committing it to a new image name. Note that only `a-z0-9-_.` are -allowed when naming images: +First save the new image by finding the container ID (using [`docker container +ls`](container_ls.md)) and then committing it to a new image name. Note that +only `a-z0-9-_.` are allowed when naming images: ```console $ docker container commit c16378f943fe rhel-httpd:latest diff --git a/docs/reference/commandline/image_rm.md b/docs/reference/commandline/image_rm.md index 5fd35e993183..f3b303da0b69 100644 --- a/docs/reference/commandline/image_rm.md +++ b/docs/reference/commandline/image_rm.md @@ -26,7 +26,7 @@ removed. This does not remove images from a registry. You cannot remove an image of a running container unless you use the `-f` option. To see all images on a host -use the [`docker image ls`](images.md) command. +use the [`docker image ls`](image_ls.md) command. ## Examples diff --git a/scripts/docs/generate-md.sh b/scripts/docs/generate-md.sh index 7b49c39341ec..9fa49ce2792d 100755 --- a/scripts/docs/generate-md.sh +++ b/scripts/docs/generate-md.sh @@ -8,9 +8,6 @@ export GO111MODULE=auto function clean { rm -rf "$buildir" - if [ -f "$(pwd)/docs/reference/commandline/docker.md" ]; then - mv "$(pwd)/docs/reference/commandline/docker.md" "$(pwd)/docs/reference/commandline/cli.md" - fi } buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX) @@ -32,12 +29,6 @@ trap clean EXIT go build -mod=vendor -modfile=vendor.mod -tags docsgen -o /tmp/docsgen ./docs/generate/generate.go ) -# yaml generation on docs repo needs the cli.md file: https://github.com/docker/cli/pull/3924#discussion_r1059986605 -# but markdown generation docker.md atm. While waiting for a fix in cli-docs-tool -# we need to first move the cli.md file to docker.md, do the generation and -# then move it back in trap handler. -mv "$(pwd)/docs/reference/commandline/cli.md" "$(pwd)/docs/reference/commandline/docker.md" - ( set -x /tmp/docsgen --formats md --source "$(pwd)/docs/reference/commandline" --target "$(pwd)/docs/reference/commandline"