github.com/panekj/cli@v0.0.0-20230304125325-467dd2f3797e/docs/reference/commandline/cli.md (about) 1 --- 2 title: "Use the Docker command line" 3 description: "Docker's CLI command description and usage" 4 keywords: "Docker, Docker documentation, CLI, command line, config.json, CLI configuration file" 5 redirect_from: 6 - /reference/commandline/cli/ 7 - /engine/reference/commandline/engine/ 8 - /engine/reference/commandline/engine_activate/ 9 - /engine/reference/commandline/engine_check/ 10 - /engine/reference/commandline/engine_update/ 11 --- 12 13 <!-- This file is maintained within the docker/cli GitHub 14 repository at https://github.com/docker/cli/. Make all 15 pull requests against that repo. If you see this file in 16 another repository, consider it read-only there, as it will 17 periodically be overwritten by the definitive file. Pull 18 requests which include edits to this file in other repositories 19 will be rejected. 20 --> 21 22 # docker 23 24 To list available commands, either run `docker` with no parameters 25 or execute `docker help`: 26 27 <!---MARKER_GEN_START--> 28 The base command for the Docker CLI. 29 30 ### Subcommands 31 32 | Name | Description | 33 |:------------------------------|:------------------------------------------------------------------------------| 34 | [`attach`](attach.md) | Attach local standard input, output, and error streams to a running container | 35 | [`build`](build.md) | Build an image from a Dockerfile | 36 | [`builder`](builder.md) | Manage builds | 37 | [`checkpoint`](checkpoint.md) | Manage checkpoints | 38 | [`commit`](commit.md) | Create a new image from a container's changes | 39 | [`config`](config.md) | Manage Swarm configs | 40 | [`container`](container.md) | Manage containers | 41 | [`context`](context.md) | Manage contexts | 42 | [`cp`](cp.md) | Copy files/folders between a container and the local filesystem | 43 | [`create`](create.md) | Create a new container | 44 | [`diff`](diff.md) | Inspect changes to files or directories on a container's filesystem | 45 | [`events`](events.md) | Get real time events from the server | 46 | [`exec`](exec.md) | Execute a command in a running container | 47 | [`export`](export.md) | Export a container's filesystem as a tar archive | 48 | [`history`](history.md) | Show the history of an image | 49 | [`image`](image.md) | Manage images | 50 | [`images`](images.md) | List images | 51 | [`import`](import.md) | Import the contents from a tarball to create a filesystem image | 52 | [`info`](info.md) | Display system-wide information | 53 | [`inspect`](inspect.md) | Return low-level information on Docker objects | 54 | [`kill`](kill.md) | Kill one or more running containers | 55 | [`load`](load.md) | Load an image from a tar archive or STDIN | 56 | [`login`](login.md) | Log in to a registry | 57 | [`logout`](logout.md) | Log out from a registry | 58 | [`logs`](logs.md) | Fetch the logs of a container | 59 | [`manifest`](manifest.md) | Manage Docker image manifests and manifest lists | 60 | [`network`](network.md) | Manage networks | 61 | [`node`](node.md) | Manage Swarm nodes | 62 | [`pause`](pause.md) | Pause all processes within one or more containers | 63 | [`plugin`](plugin.md) | Manage plugins | 64 | [`port`](port.md) | List port mappings or a specific mapping for the container | 65 | [`ps`](ps.md) | List containers | 66 | [`pull`](pull.md) | Download an image from a registry | 67 | [`push`](push.md) | Upload an image to a registry | 68 | [`rename`](rename.md) | Rename a container | 69 | [`restart`](restart.md) | Restart one or more containers | 70 | [`rm`](rm.md) | Remove one or more containers | 71 | [`rmi`](rmi.md) | Remove one or more images | 72 | [`run`](run.md) | Create and run a new container from an image | 73 | [`save`](save.md) | Save one or more images to a tar archive (streamed to STDOUT by default) | 74 | [`search`](search.md) | Search Docker Hub for images | 75 | [`secret`](secret.md) | Manage Swarm secrets | 76 | [`service`](service.md) | Manage Swarm services | 77 | [`stack`](stack.md) | Manage Swarm stacks | 78 | [`start`](start.md) | Start one or more stopped containers | 79 | [`stats`](stats.md) | Display a live stream of container(s) resource usage statistics | 80 | [`stop`](stop.md) | Stop one or more running containers | 81 | [`swarm`](swarm.md) | Manage Swarm | 82 | [`system`](system.md) | Manage Docker | 83 | [`tag`](tag.md) | Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE | 84 | [`top`](top.md) | Display the running processes of a container | 85 | [`trust`](trust.md) | Manage trust on Docker images | 86 | [`unpause`](unpause.md) | Unpause all processes within one or more containers | 87 | [`update`](update.md) | Update configuration of one or more containers | 88 | [`version`](version.md) | Show the Docker version information | 89 | [`volume`](volume.md) | Manage volumes | 90 | [`wait`](wait.md) | Block until one or more containers stop, then print their exit codes | 91 92 93 ### Options 94 95 | Name | Type | Default | Description | 96 |:--------------------|:---------|:-------------------------|:--------------------------------------------------------------------------------------------------------------------------------------| 97 | `--config` | `string` | `/root/.docker` | Location of client config files | 98 | `-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`) | 99 | `-D`, `--debug` | | | Enable debug mode | 100 | `-H`, `--host` | `list` | | Daemon socket(s) to connect to | 101 | `-l`, `--log-level` | `string` | `info` | Set the logging level (`debug`, `info`, `warn`, `error`, `fatal`) | 102 | `--tls` | | | Use TLS; implied by --tlsverify | 103 | `--tlscacert` | `string` | `/root/.docker/ca.pem` | Trust certs signed only by this CA | 104 | `--tlscert` | `string` | `/root/.docker/cert.pem` | Path to TLS certificate file | 105 | `--tlskey` | `string` | `/root/.docker/key.pem` | Path to TLS key file | 106 | `--tlsverify` | | | Use TLS and verify the remote | 107 108 109 <!---MARKER_GEN_END--> 110 111 ## Description 112 113 Depending on your Docker system configuration, you may be required to preface 114 each `docker` command with `sudo`. To avoid having to use `sudo` with the 115 `docker` command, your system administrator can create a Unix group called 116 `docker` and add users to it. 117 118 For more information about installing Docker or `sudo` configuration, refer to 119 the [installation](https://docs.docker.com/install/) instructions for your operating system. 120 121 ## Environment variables 122 123 The following list of environment variables are supported by the `docker` command 124 line: 125 126 | Variable | Description | 127 |:------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------| 128 | `DOCKER_API_VERSION` | Override the negotiated API version to use for debugging (e.g. `1.19`) | 129 | `DOCKER_CERT_PATH` | Location of your authentication keys. This variable is used both by the `docker` CLI and the [`dockerd` daemon](dockerd.md) | 130 | `DOCKER_CONFIG` | The location of your client configuration files. | 131 | `DOCKER_CONTENT_TRUST_SERVER` | The URL of the Notary server to use. Defaults to the same URL as the registry. | 132 | `DOCKER_CONTENT_TRUST` | When set Docker uses notary to sign and verify images. Equates to `--disable-content-trust=false` for build, create, pull, push, run. | 133 | `DOCKER_CONTEXT` | Name of the `docker context` to use (overrides `DOCKER_HOST` env var and default context set with `docker context use`) | 134 | `DOCKER_DEFAULT_PLATFORM` | Default platform for commands that take the `--platform` flag. | 135 | `DOCKER_HIDE_LEGACY_COMMANDS` | When set, Docker hides "legacy" top-level commands (such as `docker rm`, and `docker pull`) in `docker help` output, and only `Management commands` per object-type (e.g., `docker container`) are printed. This may become the default in a future release, at which point this environment-variable is removed. | 136 | `DOCKER_HOST` | Daemon socket to connect to. | 137 | `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) | 138 | `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`). | 139 140 Because Docker is developed using Go, you can also use any environment 141 variables used by the Go runtime. In particular, you may find these useful: 142 143 * `HTTP_PROXY` 144 * `HTTPS_PROXY` 145 * `NO_PROXY` 146 147 These Go environment variables are case-insensitive. See the 148 [Go specification](https://golang.org/pkg/net/http/) for details on these 149 variables. 150 151 ## Configuration files 152 153 By default, the Docker command line stores its configuration files in a 154 directory called `.docker` within your `$HOME` directory. 155 156 Docker manages most of the files in the configuration directory 157 and you should not modify them. However, you *can* modify the 158 `config.json` file to control certain aspects of how the `docker` 159 command behaves. 160 161 You can modify the `docker` command behavior using environment 162 variables or command-line options. You can also use options within 163 `config.json` to modify some of the same behavior. If an environment variable 164 and the `--config` flag are set, the flag takes precedent over the environment 165 variable. Command line options override environment variables and environment 166 variables override properties you specify in a `config.json` file. 167 168 169 ### Change the `.docker` directory 170 171 To specify a different directory, use the `DOCKER_CONFIG` 172 environment variable or the `--config` command line option. If both are 173 specified, then the `--config` option overrides the `DOCKER_CONFIG` environment 174 variable. The example below overrides the `docker ps` command using a 175 `config.json` file located in the `~/testconfigs/` directory. 176 177 ```console 178 $ docker --config ~/testconfigs/ ps 179 ``` 180 181 This flag only applies to whatever command is being ran. For persistent 182 configuration, you can set the `DOCKER_CONFIG` environment variable in your 183 shell (e.g. `~/.profile` or `~/.bashrc`). The example below sets the new 184 directory to be `HOME/newdir/.docker`. 185 186 ```console 187 $ echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile 188 ``` 189 190 ## Docker CLI configuration file (`config.json`) properties 191 192 <a name="configjson-properties"><!-- included for deep-links to old section --></a> 193 194 Use the Docker CLI configuration to customize settings for the `docker` CLI. The 195 configuration file uses JSON formatting, and properties: 196 197 By default, configuration file is stored in `~/.docker/config.json`. Refer to the 198 [change the `.docker` directory](#change-the-docker-directory) section to use a 199 different location. 200 201 > **Warning** 202 > 203 > The configuration file and other files inside the `~/.docker` configuration 204 > directory may contain sensitive information, such as authentication information 205 > for proxies or, depending on your credential store, credentials for your image 206 > registries. Review your configuration file's content before sharing with others, 207 > and prevent committing the file to version control. 208 209 ### Customize the default output format for commands 210 211 These fields allow you to customize the default output format for some commands 212 if no `--format` flag is provided. 213 214 | Property | Description | 215 |:-----------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 216 | `configFormat` | Custom default format for `docker config ls` output. Refer to the [**format the output** section in the `docker config ls` documentation](config_ls.md#format) for a list of supported formatting directives. | 217 | `imagesFormat` | Custom default format for `docker images` / `docker image ls` output. Refer to the [**format the output** section in the `docker images` documentation](images.md#format) for a list of supported formatting directives. | 218 | `nodesFormat` | Custom default format for `docker node ls` output. Refer to the [**formatting** section in the `docker node ls` documentation](node_ls.md#format) for a list of supported formatting directives. | 219 | `pluginsFormat` | Custom default format for `docker plugin ls` output. Refer to the [**formatting** section in the `docker plugin ls` documentation](plugin_ls.md#format) for a list of supported formatting directives. | 220 | `psFormat` | Custom default format for `docker ps` / `docker container ps` output. Refer to the [**formatting** section in the `docker ps` documentation](ps.md#format) for a list of supported formatting directives. | 221 | `secretFormat` | Custom default format for `docker secret ls` output. Refer to the [**format the output** section in the `docker secret ls` documentation](secret_ls.md#format) for a list of supported formatting directives. | 222 | `serviceInspectFormat` | Custom default format for `docker service inspect` output. Refer to the [**formatting** section in the `docker service inspect` documentation](service_inspect.md#format) for a list of supported formatting directives. | 223 | `servicesFormat` | Custom default format for `docker service ls` output. Refer to the [**formatting** section in the `docker service ls` documentation](service_ls.md#format) for a list of supported formatting directives. | 224 | `statsFormat` | Custom default format for `docker stats` output. Refer to the [**formatting** section in the `docker stats` documentation](stats.md#format) for a list of supported formatting directives. | 225 226 227 ### Custom HTTP headers 228 229 The property `HttpHeaders` specifies a set of headers to include in all messages 230 sent from the Docker client to the daemon. Docker does not try to interpret or 231 understand these headers; it simply puts them into the messages. Docker does 232 not allow these headers to change any headers it sets for itself. 233 234 235 ### Credential store options 236 237 The property `credsStore` specifies an external binary to serve as the default 238 credential store. When this property is set, `docker login` will attempt to 239 store credentials in the binary specified by `docker-credential-<value>` which 240 is visible on `$PATH`. If this property is not set, credentials will be stored 241 in the `auths` property of the config. For more information, see the 242 [**Credentials store** section in the `docker login` documentation](login.md#credentials-store) 243 244 The property `credHelpers` specifies a set of credential helpers to use 245 preferentially over `credsStore` or `auths` when storing and retrieving 246 credentials for specific registries. If this property is set, the binary 247 `docker-credential-<value>` will be used when storing or retrieving credentials 248 for a specific registry. For more information, see the 249 [**Credential helpers** section in the `docker login` documentation](login.md#credential-helpers) 250 251 252 ### Automatic proxy configuration for containers 253 254 The property `proxies` specifies proxy environment variables to be automatically 255 set on containers, and set as `--build-arg` on containers used during `docker build`. 256 A `"default"` set of proxies can be configured, and will be used for any docker 257 daemon that the client connects to, or a configuration per host (docker daemon), 258 for example, "https://docker-daemon1.example.com". The following properties can 259 be set for each environment: 260 261 | Property | Description | 262 |:---------------|:--------------------------------------------------------------------------------------------------------| 263 | `httpProxy` | Default value of `HTTP_PROXY` and `http_proxy` for containers, and as `--build-arg` on `docker build` | 264 | `httpsProxy` | Default value of `HTTPS_PROXY` and `https_proxy` for containers, and as `--build-arg` on `docker build` | 265 | `ftpProxy` | Default value of `FTP_PROXY` and `ftp_proxy` for containers, and as `--build-arg` on `docker build` | 266 | `noProxy` | Default value of `NO_PROXY` and `no_proxy` for containers, and as `--build-arg` on `docker build` | 267 | `allProxy` | Default value of `ALL_PROXY` and `all_proxy` for containers, and as `--build-arg` on `docker build` | 268 269 These settings are used to configure proxy settings for containers only, and not 270 used as proxy settings for the `docker` CLI or the `dockerd` daemon. Refer to the 271 [environment variables](#environment-variables) and [HTTP/HTTPS proxy](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) 272 sections for configuring proxy settings for the cli and daemon. 273 274 > **Warning** 275 > 276 > Proxy settings may contain sensitive information (for example, if the proxy 277 > requires authentication). Environment variables are stored as plain text in 278 > the container's configuration, and as such can be inspected through the remote 279 > API or committed to an image when using `docker commit`. 280 281 ### Default key-sequence to detach from containers 282 283 Once attached to a container, users detach from it and leave it running using 284 the using `CTRL-p CTRL-q` key sequence. This detach key sequence is customizable 285 using the `detachKeys` property. Specify a `<sequence>` value for the 286 property. The format of the `<sequence>` is a comma-separated list of either 287 a letter [a-Z], or the `ctrl-` combined with any of the following: 288 289 * `a-z` (a single lowercase alpha character ) 290 * `@` (at sign) 291 * `[` (left bracket) 292 * `\\` (two backward slashes) 293 * `_` (underscore) 294 * `^` (caret) 295 296 Your customization applies to all containers started in with your Docker client. 297 Users can override your custom or the default key sequence on a per-container 298 basis. To do this, the user specifies the `--detach-keys` flag with the `docker 299 attach`, `docker exec`, `docker run` or `docker start` command. 300 301 ### CLI Plugin options 302 303 The property `plugins` contains settings specific to CLI plugins. The 304 key is the plugin name, while the value is a further map of options, 305 which are specific to that plugin. 306 307 308 ### Sample configuration file 309 310 Following is a sample `config.json` file to illustrate the format used for 311 various fields: 312 313 ```json 314 {% raw %} 315 { 316 "HttpHeaders": { 317 "MyHeader": "MyValue" 318 }, 319 "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}", 320 "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}", 321 "pluginsFormat": "table {{.ID}}\t{{.Name}}\t{{.Enabled}}", 322 "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}", 323 "servicesFormat": "table {{.ID}}\t{{.Name}}\t{{.Mode}}", 324 "secretFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}", 325 "configFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}", 326 "serviceInspectFormat": "pretty", 327 "nodesFormat": "table {{.ID}}\t{{.Hostname}}\t{{.Availability}}", 328 "detachKeys": "ctrl-e,e", 329 "credsStore": "secretservice", 330 "credHelpers": { 331 "awesomereg.example.org": "hip-star", 332 "unicorn.example.com": "vcbait" 333 }, 334 "plugins": { 335 "plugin1": { 336 "option": "value" 337 }, 338 "plugin2": { 339 "anotheroption": "anothervalue", 340 "athirdoption": "athirdvalue" 341 } 342 }, 343 "proxies": { 344 "default": { 345 "httpProxy": "http://user:pass@example.com:3128", 346 "httpsProxy": "https://my-proxy.example.com:3129", 347 "noProxy": "intra.mycorp.example.com", 348 "ftpProxy": "http://user:pass@example.com:3128", 349 "allProxy": "socks://example.com:1234" 350 }, 351 "https://manager1.mycorp.example.com:2377": { 352 "httpProxy": "http://user:pass@example.com:3128", 353 "httpsProxy": "https://my-proxy.example.com:3129" 354 } 355 } 356 } 357 {% endraw %} 358 ``` 359 360 ### Experimental features 361 362 Experimental features provide early access to future product functionality. 363 These features are intended for testing and feedback, and they may change 364 between releases without warning or can be removed from a future release. 365 366 Starting with Docker 20.10, experimental CLI features are enabled by default, 367 and require no configuration to enable them. 368 369 ### Notary 370 371 If using your own notary server and a self-signed certificate or an internal 372 Certificate Authority, you need to place the certificate at 373 `tls/<registry_url>/ca.crt` in your docker config directory. 374 375 Alternatively you can trust the certificate globally by adding it to your system's 376 list of root Certificate Authorities. 377 378 ## Examples 379 380 ### Display help text 381 382 To list the help on any command just execute the command, followed by the 383 `--help` option. 384 385 ```console 386 $ docker run --help 387 388 Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] 389 390 Create and run a new container from an image 391 392 Options: 393 --add-host value Add a custom host-to-IP mapping (host:ip) (default []) 394 -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) 395 <...> 396 ``` 397 398 ### Option types 399 400 Single character command line options can be combined, so rather than 401 typing `docker run -i -t --name test busybox sh`, 402 you can write `docker run -it --name test busybox sh`. 403 404 #### Boolean 405 406 Boolean options take the form `-d=false`. The value you see in the help text is 407 the default value which is set if you do **not** specify that flag. If you 408 specify a Boolean flag without a value, this will set the flag to `true`, 409 irrespective of the default value. 410 411 For example, running `docker run -d` will set the value to `true`, so your 412 container **will** run in "detached" mode, in the background. 413 414 Options which default to `true` (e.g., `docker build --rm=true`) can only be 415 set to the non-default value by explicitly setting them to `false`: 416 417 ```console 418 $ docker build --rm=false . 419 ``` 420 421 #### Multi 422 423 You can specify options like `-a=[]` multiple times in a single command line, 424 for example in these commands: 425 426 ```console 427 $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash 428 429 $ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls 430 ``` 431 432 Sometimes, multiple options can call for a more complex value string as for 433 `-v`: 434 435 ```console 436 $ docker run -v /host:/container example/mysql 437 ``` 438 439 > **Note** 440 > 441 > Do not use the `-t` and `-a stderr` options together due to 442 > limitations in the `pty` implementation. All `stderr` in `pty` mode 443 > simply goes to `stdout`. 444 445 #### Strings and Integers 446 447 Options like `--name=""` expect a string, and they 448 can only be specified once. Options like `-c=0` 449 expect an integer, and they can only be specified once.