1--- 2title: "Use the Docker command line" 3description: "Docker's CLI command description and usage" 4keywords: "Docker, Docker documentation, CLI, command line" 5--- 6 7<!-- This file is maintained within the docker/cli GitHub 8 repository at https://github.com/docker/cli/. Make all 9 pull requests against that repo. If you see this file in 10 another repository, consider it read-only there, as it will 11 periodically be overwritten by the definitive file. Pull 12 requests which include edits to this file in other repositories 13 will be rejected. 14--> 15 16# docker 17 18To list available commands, either run `docker` with no parameters 19or execute `docker help`: 20 21```bash 22$ docker 23Usage: docker [OPTIONS] COMMAND [ARG...] 24 docker [ --help | -v | --version ] 25 26A self-sufficient runtime for containers. 27 28Options: 29 --config string Location of client config files (default "/root/.docker") 30 -D, --debug Enable debug mode 31 --help Print usage 32 -H, --host value Daemon socket(s) to connect to (default []) 33 -l, --log-level string Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info") 34 --tls Use TLS; implied by --tlsverify 35 --tlscacert string Trust certs signed only by this CA (default "/root/.docker/ca.pem") 36 --tlscert string Path to TLS certificate file (default "/root/.docker/cert.pem") 37 --tlskey string Path to TLS key file (default "/root/.docker/key.pem") 38 --tlsverify Use TLS and verify the remote 39 -v, --version Print version information and quit 40 41Commands: 42 attach Attach to a running container 43 # […] 44``` 45 46## Description 47 48Depending on your Docker system configuration, you may be required to preface 49each `docker` command with `sudo`. To avoid having to use `sudo` with the 50`docker` command, your system administrator can create a Unix group called 51`docker` and add users to it. 52 53For more information about installing Docker or `sudo` configuration, refer to 54the [installation](https://docs.docker.com/install/) instructions for your operating system. 55 56### Environment variables 57 58For easy reference, the following list of environment variables are supported 59by the `docker` command line: 60 61* `DOCKER_API_VERSION` The API version to use (e.g. `1.19`) 62* `DOCKER_CONFIG` The location of your client configuration files. 63* `DOCKER_CERT_PATH` The location of your authentication keys. 64* `DOCKER_CLI_EXPERIMENTAL` Enable experimental features for the cli (e.g. `enabled` or `disabled`) 65* `DOCKER_DRIVER` The graph driver to use. 66* `DOCKER_HOST` Daemon socket to connect to. 67* `DOCKER_NOWARN_KERNEL_VERSION` Prevent warnings that your Linux kernel is 68 unsuitable for Docker. 69* `DOCKER_RAMDISK` If set this will disable 'pivot_root'. 70* `DOCKER_STACK_ORCHESTRATOR` Configure the default orchestrator to use when using `docker stack` management commands. 71* `DOCKER_TLS` When set Docker uses TLS. 72* `DOCKER_TLS_VERIFY` When set Docker uses TLS and verifies the remote. 73* `DOCKER_CONTENT_TRUST` When set Docker uses notary to sign and verify images. 74 Equates to `--disable-content-trust=false` for build, create, pull, push, run. 75* `DOCKER_CONTENT_TRUST_SERVER` The URL of the Notary server to use. This defaults 76 to the same URL as the registry. 77* `DOCKER_HIDE_LEGACY_COMMANDS` When set, Docker hides "legacy" top-level commands (such as `docker rm`, and 78 `docker pull`) in `docker help` output, and only `Management commands` per object-type (e.g., `docker container`) are 79 printed. This may become the default in a future release, at which point this environment-variable is removed. 80* `DOCKER_TMPDIR` Location for temporary Docker files. 81 82Because Docker is developed using Go, you can also use any environment 83variables used by the Go runtime. In particular, you may find these useful: 84 85* `HTTP_PROXY` 86* `HTTPS_PROXY` 87* `NO_PROXY` 88 89These Go environment variables are case-insensitive. See the 90[Go specification](http://golang.org/pkg/net/http/) for details on these 91variables. 92 93### Configuration files 94 95By default, the Docker command line stores its configuration files in a 96directory called `.docker` within your `$HOME` directory. However, you can 97specify a different location via the `DOCKER_CONFIG` environment variable 98or the `--config` command line option. If both are specified, then the 99`--config` option overrides the `DOCKER_CONFIG` environment variable. 100For example: 101 102 docker --config ~/testconfigs/ ps 103 104Instructs Docker to use the configuration files in your `~/testconfigs/` 105directory when running the `ps` command. 106 107Docker manages most of the files in the configuration directory 108and you should not modify them. However, you *can modify* the 109`config.json` file to control certain aspects of how the `docker` 110command behaves. 111 112Currently, you can modify the `docker` command behavior using environment 113variables or command-line options. You can also use options within 114`config.json` to modify some of the same behavior. When using these 115mechanisms, you must keep in mind the order of precedence among them. Command 116line options override environment variables and environment variables override 117properties you specify in a `config.json` file. 118 119The `config.json` file stores a JSON encoding of several properties: 120 121The property `HttpHeaders` specifies a set of headers to include in all messages 122sent from the Docker client to the daemon. Docker does not try to interpret or 123understand these header; it simply puts them into the messages. Docker does 124not allow these headers to change any headers it sets for itself. 125 126The property `psFormat` specifies the default format for `docker ps` output. 127When the `--format` flag is not provided with the `docker ps` command, 128Docker's client uses this property. If this property is not set, the client 129falls back to the default table format. For a list of supported formatting 130directives, see the 131[**Formatting** section in the `docker ps` documentation](ps.md) 132 133The property `imagesFormat` specifies the default format for `docker images` output. 134When the `--format` flag is not provided with the `docker images` command, 135Docker's client uses this property. If this property is not set, the client 136falls back to the default table format. For a list of supported formatting 137directives, see the [**Formatting** section in the `docker images` documentation](images.md) 138 139The property `pluginsFormat` specifies the default format for `docker plugin ls` output. 140When the `--format` flag is not provided with the `docker plugin ls` command, 141Docker's client uses this property. If this property is not set, the client 142falls back to the default table format. For a list of supported formatting 143directives, see the [**Formatting** section in the `docker plugin ls` documentation](plugin_ls.md) 144 145The property `servicesFormat` specifies the default format for `docker 146service ls` output. When the `--format` flag is not provided with the 147`docker service ls` command, Docker's client uses this property. If this 148property is not set, the client falls back to the default json format. For a 149list of supported formatting directives, see the 150[**Formatting** section in the `docker service ls` documentation](service_ls.md) 151 152The property `serviceInspectFormat` specifies the default format for `docker 153service inspect` output. When the `--format` flag is not provided with the 154`docker service inspect` command, Docker's client uses this property. If this 155property is not set, the client falls back to the default json format. For a 156list of supported formatting directives, see the 157[**Formatting** section in the `docker service inspect` documentation](service_inspect.md) 158 159The property `statsFormat` specifies the default format for `docker 160stats` output. When the `--format` flag is not provided with the 161`docker stats` command, Docker's client uses this property. If this 162property is not set, the client falls back to the default table 163format. For a list of supported formatting directives, see 164[**Formatting** section in the `docker stats` documentation](stats.md) 165 166The property `secretFormat` specifies the default format for `docker 167secret ls` output. When the `--format` flag is not provided with the 168`docker secret ls` command, Docker's client uses this property. If this 169property is not set, the client falls back to the default table 170format. For a list of supported formatting directives, see 171[**Formatting** section in the `docker secret ls` documentation](secret_ls.md) 172 173 174The property `nodesFormat` specifies the default format for `docker node ls` output. 175When the `--format` flag is not provided with the `docker node ls` command, 176Docker's client uses the value of `nodesFormat`. If the value of `nodesFormat` is not set, 177the client uses the default table format. For a list of supported formatting 178directives, see the [**Formatting** section in the `docker node ls` documentation](node_ls.md) 179 180The property `configFormat` specifies the default format for `docker 181config ls` output. When the `--format` flag is not provided with the 182`docker config ls` command, Docker's client uses this property. If this 183property is not set, the client falls back to the default table 184format. For a list of supported formatting directives, see 185[**Formatting** section in the `docker config ls` documentation](config_ls.md) 186 187The property `credsStore` specifies an external binary to serve as the default 188credential store. When this property is set, `docker login` will attempt to 189store credentials in the binary specified by `docker-credential-<value>` which 190is visible on `$PATH`. If this property is not set, credentials will be stored 191in the `auths` property of the config. For more information, see the 192[**Credentials store** section in the `docker login` documentation](login.md#credentials-store) 193 194The property `credHelpers` specifies a set of credential helpers to use 195preferentially over `credsStore` or `auths` when storing and retrieving 196credentials for specific registries. If this property is set, the binary 197`docker-credential-<value>` will be used when storing or retrieving credentials 198for a specific registry. For more information, see the 199[**Credential helpers** section in the `docker login` documentation](login.md#credential-helpers) 200 201The property `stackOrchestrator` specifies the default orchestrator to use when 202running `docker stack` management commands. Valid values are `"swarm"`, 203`"kubernetes"`, and `"all"`. This property can be overridden with the 204`DOCKER_STACK_ORCHESTRATOR` environment variable, or the `--orchestrator` flag. 205 206Once attached to a container, users detach from it and leave it running using 207the using `CTRL-p CTRL-q` key sequence. This detach key sequence is customizable 208using the `detachKeys` property. Specify a `<sequence>` value for the 209property. The format of the `<sequence>` is a comma-separated list of either 210a letter [a-Z], or the `ctrl-` combined with any of the following: 211 212* `a-z` (a single lowercase alpha character ) 213* `@` (at sign) 214* `[` (left bracket) 215* `\\` (two backward slashes) 216* `_` (underscore) 217* `^` (caret) 218 219Your customization applies to all containers started in with your Docker client. 220Users can override your custom or the default key sequence on a per-container 221basis. To do this, the user specifies the `--detach-keys` flag with the `docker 222attach`, `docker exec`, `docker run` or `docker start` command. 223 224Following is a sample `config.json` file: 225 226```json 227{% raw %} 228{ 229 "HttpHeaders": { 230 "MyHeader": "MyValue" 231 }, 232 "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}", 233 "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}", 234 "pluginsFormat": "table {{.ID}}\t{{.Name}}\t{{.Enabled}}", 235 "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}", 236 "servicesFormat": "table {{.ID}}\t{{.Name}}\t{{.Mode}}", 237 "secretFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}", 238 "configFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}", 239 "serviceInspectFormat": "pretty", 240 "nodesFormat": "table {{.ID}}\t{{.Hostname}}\t{{.Availability}}", 241 "detachKeys": "ctrl-e,e", 242 "credsStore": "secretservice", 243 "credHelpers": { 244 "awesomereg.example.org": "hip-star", 245 "unicorn.example.com": "vcbait" 246 }, 247 "stackOrchestrator": "kubernetes" 248} 249{% endraw %} 250``` 251 252### Notary 253 254If using your own notary server and a self-signed certificate or an internal 255Certificate Authority, you need to place the certificate at 256`tls/<registry_url>/ca.crt` in your docker config directory. 257 258Alternatively you can trust the certificate globally by adding it to your system's 259list of root Certificate Authorities. 260 261## Examples 262 263### Display help text 264 265To list the help on any command just execute the command, followed by the 266`--help` option. 267 268 $ docker run --help 269 270 Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] 271 272 Run a command in a new container 273 274 Options: 275 --add-host value Add a custom host-to-IP mapping (host:ip) (default []) 276 -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) 277 ... 278 279### Option types 280 281Single character command line options can be combined, so rather than 282typing `docker run -i -t --name test busybox sh`, 283you can write `docker run -it --name test busybox sh`. 284 285#### Boolean 286 287Boolean options take the form `-d=false`. The value you see in the help text is 288the default value which is set if you do **not** specify that flag. If you 289specify a Boolean flag without a value, this will set the flag to `true`, 290irrespective of the default value. 291 292For example, running `docker run -d` will set the value to `true`, so your 293container **will** run in "detached" mode, in the background. 294 295Options which default to `true` (e.g., `docker build --rm=true`) can only be 296set to the non-default value by explicitly setting them to `false`: 297 298```bash 299$ docker build --rm=false . 300``` 301 302#### Multi 303 304You can specify options like `-a=[]` multiple times in a single command line, 305for example in these commands: 306 307```bash 308$ docker run -a stdin -a stdout -i -t ubuntu /bin/bash 309 310$ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls 311``` 312 313Sometimes, multiple options can call for a more complex value string as for 314`-v`: 315 316```bash 317$ docker run -v /host:/container example/mysql 318``` 319 320> **Note**: Do not use the `-t` and `-a stderr` options together due to 321> limitations in the `pty` implementation. All `stderr` in `pty` mode 322> simply goes to `stdout`. 323 324#### Strings and Integers 325 326Options like `--name=""` expect a string, and they 327can only be specified once. Options like `-c=0` 328expect an integer, and they can only be specified once. 329