github.com/khulnasoft/cli@v0.0.0-20240402070845-01bcad7beefa/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 aliases: 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 The base command for the Docker CLI is `docker`. For information about the 14 available flags and subcommands, refer to the [CLI reference](https://docs.docker.com/reference/cli/docker/) 15 16 Depending on your Docker system configuration, you may be required to preface 17 each `docker` command with `sudo`. To avoid having to use `sudo` with the 18 `docker` command, your system administrator can create a Unix group called 19 `docker` and add users to it. 20 21 For more information about installing Docker or `sudo` configuration, refer to 22 the [installation](https://docs.docker.com/install/) instructions for your operating system. 23 24 ## Environment variables 25 26 The following list of environment variables are supported by the `docker` command 27 line: 28 29 | Variable | Description | 30 | :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 31 | `DOCKER_API_VERSION` | Override the negotiated API version to use for debugging (e.g. `1.19`) | 32 | `DOCKER_CERT_PATH` | Location of your authentication keys. This variable is used both by the `docker` CLI and the [`dockerd` daemon](https://docs.docker.com/reference/cli/dockerd/) | 33 | `DOCKER_CONFIG` | The location of your client configuration files. | 34 | `DOCKER_CONTENT_TRUST_SERVER` | The URL of the Notary server to use. Defaults to the same URL as the registry. | 35 | `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. | 36 | `DOCKER_CONTEXT` | Name of the `docker context` to use (overrides `DOCKER_HOST` env var and default context set with `docker context use`) | 37 | `DOCKER_DEFAULT_PLATFORM` | Default platform for commands that take the `--platform` flag. | 38 | `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. | 39 | `DOCKER_HOST` | Daemon socket to connect to. | 40 | `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. | 41 | `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](https://docs.docker.com/reference/cli/dockerd/) | 42 | `BUILDKIT_PROGRESS` | Set type of progress output (`auto`, `plain`, `tty`, `rawjson`) when [building](https://docs.docker.com/reference/cli/docker/image/build/) with [BuildKit backend](https://docs.docker.com/build/buildkit/). Use plain to show container output (default `auto`). | 43 44 Because Docker is developed using Go, you can also use any environment 45 variables used by the Go runtime. In particular, you may find these useful: 46 47 | Variable | Description | 48 |:--------------|:-------------------------------------------------------------------------------| 49 | `HTTP_PROXY` | Proxy URL for HTTP requests unless overridden by NoProxy. | 50 | `HTTPS_PROXY` | Proxy URL for HTTPS requests unless overridden by NoProxy. | 51 | `NO_PROXY` | Comma-separated values specifying hosts that should be excluded from proxying. | 52 53 See the [Go specification](https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config) 54 for details on these variables. 55 56 ## Configuration files 57 58 By default, the Docker command line stores its configuration files in a 59 directory called `.docker` within your `$HOME` directory. 60 61 Docker manages most of the files in the configuration directory 62 and you shouldn't modify them. However, you can modify the 63 `config.json` file to control certain aspects of how the `docker` 64 command behaves. 65 66 You can modify the `docker` command behavior using environment 67 variables or command-line options. You can also use options within 68 `config.json` to modify some of the same behavior. If an environment variable 69 and the `--config` flag are set, the flag takes precedent over the environment 70 variable. Command line options override environment variables and environment 71 variables override properties you specify in a `config.json` file. 72 73 ### Change the `.docker` directory 74 75 To specify a different directory, use the `DOCKER_CONFIG` 76 environment variable or the `--config` command line option. If both are 77 specified, then the `--config` option overrides the `DOCKER_CONFIG` environment 78 variable. The example below overrides the `docker ps` command using a 79 `config.json` file located in the `~/testconfigs/` directory. 80 81 ```console 82 $ docker --config ~/testconfigs/ ps 83 ``` 84 85 This flag only applies to whatever command is being ran. For persistent 86 configuration, you can set the `DOCKER_CONFIG` environment variable in your 87 shell (e.g. `~/.profile` or `~/.bashrc`). The example below sets the new 88 directory to be `HOME/newdir/.docker`. 89 90 ```console 91 $ echo export DOCKER_CONFIG=$HOME/newdir/.docker > ~/.profile 92 ``` 93 94 ## Docker CLI configuration file (`config.json`) properties 95 96 <a name="configjson-properties"><!-- included for deep-links to old section --></a> 97 98 Use the Docker CLI configuration to customize settings for the `docker` CLI. The 99 configuration file uses JSON formatting, and properties: 100 101 By default, configuration file is stored in `~/.docker/config.json`. Refer to the 102 [change the `.docker` directory](#change-the-docker-directory) section to use a 103 different location. 104 105 > **Warning** 106 > 107 > The configuration file and other files inside the `~/.docker` configuration 108 > directory may contain sensitive information, such as authentication information 109 > for proxies or, depending on your credential store, credentials for your image 110 > registries. Review your configuration file's content before sharing with others, 111 > and prevent committing the file to version control. 112 113 ### Customize the default output format for commands 114 115 These fields lets you customize the default output format for some commands 116 if no `--format` flag is provided. 117 118 | Property | Description | 119 | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 120 | `configFormat` | Custom default format for `docker config ls` output. See [`docker config ls`](https://docs.docker.com/reference/cli/docker/config/ls/#format) for a list of supported formatting directives. | 121 | `imagesFormat` | Custom default format for `docker images` / `docker image ls` output. See [`docker images`](https://docs.docker.com/reference/cli/docker/image/ls/#format) for a list of supported formatting directives. | 122 | `networksFormat` | Custom default format for `docker network ls` output. See [`docker network ls`](https://docs.docker.com/reference/cli/docker/network/ls/#format) for a list of supported formatting directives. | 123 | `nodesFormat` | Custom default format for `docker node ls` output. See [`docker node ls`](https://docs.docker.com/reference/cli/docker/node/ls/#format) for a list of supported formatting directives. | 124 | `pluginsFormat` | Custom default format for `docker plugin ls` output. See [`docker plugin ls`](https://docs.docker.com/reference/cli/docker/plugin/ls/#format) for a list of supported formatting directives. | 125 | `psFormat` | Custom default format for `docker ps` / `docker container ps` output. See [`docker ps`](https://docs.docker.com/reference/cli/docker/container/ls/#format) for a list of supported formatting directives. | 126 | `secretFormat` | Custom default format for `docker secret ls` output. See [`docker secret ls`](https://docs.docker.com/reference/cli/docker/secret/ls/#format) for a list of supported formatting directives. | 127 | `serviceInspectFormat` | Custom default format for `docker service inspect` output. See [`docker service inspect`](https://docs.docker.com/reference/cli/docker/service/inspect/#format) for a list of supported formatting directives. | 128 | `servicesFormat` | Custom default format for `docker service ls` output. See [`docker service ls`](https://docs.docker.com/reference/cli/docker/service/ls/#format) for a list of supported formatting directives. | 129 | `statsFormat` | Custom default format for `docker stats` output. See [`docker stats`](https://docs.docker.com/reference/cli/docker/container/stats/#format) for a list of supported formatting directives. | 130 | `tasksFormat` | Custom default format for `docker stack ps` output. See [`docker stack ps`](https://docs.docker.com/reference/cli/docker/stack/ps/#format) for a list of supported formatting directives. | 131 | `volumesFormat` | Custom default format for `docker volume ls` output. See [`docker volume ls`](https://docs.docker.com/reference/cli/docker/volume/ls/#format) for a list of supported formatting directives. | 132 133 ### Custom HTTP headers 134 135 The property `HttpHeaders` specifies a set of headers to include in all messages 136 sent from the Docker client to the daemon. Docker doesn't try to interpret or 137 understand these headers; it simply puts them into the messages. Docker does 138 not allow these headers to change any headers it sets for itself. 139 140 ### Credential store options 141 142 The property `credsStore` specifies an external binary to serve as the default 143 credential store. When this property is set, `docker login` will attempt to 144 store credentials in the binary specified by `docker-credential-<value>` which 145 is visible on `$PATH`. If this property isn't set, credentials are stored 146 in the `auths` property of the CLI configuration file. For more information, 147 see the [**Credential stores** section in the `docker login` documentation](https://docs.docker.com/reference/cli/docker/login/#credential-stores) 148 149 The property `credHelpers` specifies a set of credential helpers to use 150 preferentially over `credsStore` or `auths` when storing and retrieving 151 credentials for specific registries. If this property is set, the binary 152 `docker-credential-<value>` will be used when storing or retrieving credentials 153 for a specific registry. For more information, see the 154 [**Credential helpers** section in the `docker login` documentation](https://docs.docker.com/reference/cli/docker/login/#credential-helpers) 155 156 ### Automatic proxy configuration for containers 157 158 The property `proxies` specifies proxy environment variables to be automatically 159 set on containers, and set as `--build-arg` on containers used during `docker build`. 160 A `"default"` set of proxies can be configured, and will be used for any Docker 161 daemon that the client connects to, or a configuration per host (Docker daemon), 162 for example, `https://docker-daemon1.example.com`. The following properties can 163 be set for each environment: 164 165 | Property | Description | 166 |:---------------|:--------------------------------------------------------------------------------------------------------| 167 | `httpProxy` | Default value of `HTTP_PROXY` and `http_proxy` for containers, and as `--build-arg` on `docker build` | 168 | `httpsProxy` | Default value of `HTTPS_PROXY` and `https_proxy` for containers, and as `--build-arg` on `docker build` | 169 | `ftpProxy` | Default value of `FTP_PROXY` and `ftp_proxy` for containers, and as `--build-arg` on `docker build` | 170 | `noProxy` | Default value of `NO_PROXY` and `no_proxy` for containers, and as `--build-arg` on `docker build` | 171 | `allProxy` | Default value of `ALL_PROXY` and `all_proxy` for containers, and as `--build-arg` on `docker build` | 172 173 These settings are used to configure proxy settings for containers only, and not 174 used as proxy settings for the `docker` CLI or the `dockerd` daemon. Refer to the 175 [environment variables](#environment-variables) and [HTTP/HTTPS proxy](https://docs.docker.com/config/daemon/systemd/#httphttps-proxy) 176 sections for configuring proxy settings for the cli and daemon. 177 178 > **Warning** 179 > 180 > Proxy settings may contain sensitive information (for example, if the proxy 181 > requires authentication). Environment variables are stored as plain text in 182 > the container's configuration, and as such can be inspected through the remote 183 > API or committed to an image when using `docker commit`. 184 { .warning } 185 186 ### Default key-sequence to detach from containers 187 188 Once attached to a container, users detach from it and leave it running using 189 the using `CTRL-p CTRL-q` key sequence. This detach key sequence is customizable 190 using the `detachKeys` property. Specify a `<sequence>` value for the 191 property. The format of the `<sequence>` is a comma-separated list of either 192 a letter [a-Z], or the `ctrl-` combined with any of the following: 193 194 * `a-z` (a single lowercase alpha character ) 195 * `@` (at sign) 196 * `[` (left bracket) 197 * `\\` (two backward slashes) 198 * `_` (underscore) 199 * `^` (caret) 200 201 Your customization applies to all containers started in with your Docker client. 202 Users can override your custom or the default key sequence on a per-container 203 basis. To do this, the user specifies the `--detach-keys` flag with the `docker 204 attach`, `docker exec`, `docker run` or `docker start` command. 205 206 ### CLI plugin options 207 208 The property `plugins` contains settings specific to CLI plugins. The 209 key is the plugin name, while the value is a further map of options, 210 which are specific to that plugin. 211 212 ### Sample configuration file 213 214 Following is a sample `config.json` file to illustrate the format used for 215 various fields: 216 217 ```json 218 { 219 "HttpHeaders": { 220 "MyHeader": "MyValue" 221 }, 222 "psFormat": "table {{.ID}}\\t{{.Image}}\\t{{.Command}}\\t{{.Labels}}", 223 "imagesFormat": "table {{.ID}}\\t{{.Repository}}\\t{{.Tag}}\\t{{.CreatedAt}}", 224 "pluginsFormat": "table {{.ID}}\t{{.Name}}\t{{.Enabled}}", 225 "statsFormat": "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}", 226 "servicesFormat": "table {{.ID}}\t{{.Name}}\t{{.Mode}}", 227 "secretFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}", 228 "configFormat": "table {{.ID}}\t{{.Name}}\t{{.CreatedAt}}\t{{.UpdatedAt}}", 229 "serviceInspectFormat": "pretty", 230 "nodesFormat": "table {{.ID}}\t{{.Hostname}}\t{{.Availability}}", 231 "detachKeys": "ctrl-e,e", 232 "credsStore": "secretservice", 233 "credHelpers": { 234 "awesomereg.example.org": "hip-star", 235 "unicorn.example.com": "vcbait" 236 }, 237 "plugins": { 238 "plugin1": { 239 "option": "value" 240 }, 241 "plugin2": { 242 "anotheroption": "anothervalue", 243 "athirdoption": "athirdvalue" 244 } 245 }, 246 "proxies": { 247 "default": { 248 "httpProxy": "http://user:pass@example.com:3128", 249 "httpsProxy": "https://my-proxy.example.com:3129", 250 "noProxy": "intra.mycorp.example.com", 251 "ftpProxy": "http://user:pass@example.com:3128", 252 "allProxy": "socks://example.com:1234" 253 }, 254 "https://manager1.mycorp.example.com:2377": { 255 "httpProxy": "http://user:pass@example.com:3128", 256 "httpsProxy": "https://my-proxy.example.com:3129" 257 } 258 } 259 } 260 ``` 261 262 ### Experimental features 263 264 Experimental features provide early access to future product functionality. 265 These features are intended for testing and feedback, and they may change 266 between releases without warning or can be removed from a future release. 267 268 Starting with Docker 20.10, experimental CLI features are enabled by default, 269 and require no configuration to enable them. 270 271 ### Notary 272 273 If using your own notary server and a self-signed certificate or an internal 274 Certificate Authority, you need to place the certificate at 275 `tls/<registry_url>/ca.crt` in your Docker config directory. 276 277 Alternatively you can trust the certificate globally by adding it to your system's 278 list of root Certificate Authorities. 279 280 ## Examples 281 282 ### <a name="host"></a> Specify daemon host (-H, --host) 283 284 You can use the `-H`, `--host` flag to specify a socket to use when you invoke 285 a `docker` command. You can use the following protocols: 286 287 | Scheme | Description | Example | 288 |----------------------------------------|---------------------------|----------------------------------| 289 | `unix://[<path>]` | Unix socket (Linux only) | `unix:///var/run/docker.sock` | 290 | `tcp://[<IP or host>[:port]]` | TCP connection | `tcp://174.17.0.1:2376` | 291 | `ssh://[username@]<IP or host>[:port]` | SSH connection | `ssh://user@192.168.64.5` | 292 | `npipe://[<name>]` | Named pipe (Windows only) | `npipe:////./pipe/docker_engine` | 293 294 If you don't specify the `-H` flag, and you're not using a custom 295 [context](https://docs.docker.com/engine/context/working-with-contexts), 296 commands use the following default sockets: 297 298 - `unix:///var/run/docker.sock` on macOS and Linux 299 - `npipe:////./pipe/docker_engine` on Windows 300 301 To achieve a similar effect without having to specify the `-H` flag for every 302 command, you could also [create a context](https://docs.docker.com/reference/cli/docker/context/create/), 303 or alternatively, use the 304 [`DOCKER_HOST` environment variable](#environment-variables). 305 306 For more information about the `-H` flag, see 307 [Daemon socket option](https://docs.docker.com/reference/cli/dockerd/#daemon-socket-option). 308 309 #### Using TCP sockets 310 311 The following example shows how to invoke `docker ps` over TCP, to a remote 312 daemon with IP address `174.17.0.1`, listening on port `2376`: 313 314 ```console 315 $ docker -H tcp://174.17.0.1:2376 ps 316 ``` 317 318 > **Note** 319 > 320 > By convention, the Docker daemon uses port `2376` for secure TLS connections, 321 > and port `2375` for insecure, non-TLS connections. 322 323 #### Using SSH sockets 324 325 When you use SSH invoke a command on a remote daemon, the request gets forwarded 326 to the `/var/run/docker.sock` Unix socket on the SSH host. 327 328 ```console 329 $ docker -H ssh://user@192.168.64.5 ps 330 ``` 331 332 You can optionally specify the location of the socket by appending a path 333 component to the end of the SSH address. 334 335 ```console 336 $ docker -H ssh://user@192.168.64.5/var/run/docker.sock ps 337 ``` 338 339 ### Display help text 340 341 To list the help on any command just execute the command, followed by the 342 `--help` option. 343 344 ```console 345 $ docker run --help 346 347 Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] 348 349 Create and run a new container from an image 350 351 Options: 352 --add-host value Add a custom host-to-IP mapping (host:ip) (default []) 353 -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) 354 <...> 355 ``` 356 357 ### Option types 358 359 Single character command line options can be combined, so rather than 360 typing `docker run -i -t --name test busybox sh`, 361 you can write `docker run -it --name test busybox sh`. 362 363 #### Boolean 364 365 Boolean options take the form `-d=false`. The value you see in the help text is 366 the default value which is set if you do **not** specify that flag. If you 367 specify a Boolean flag without a value, this will set the flag to `true`, 368 irrespective of the default value. 369 370 For example, running `docker run -d` will set the value to `true`, so your 371 container **will** run in "detached" mode, in the background. 372 373 Options which default to `true` (e.g., `docker build --rm=true`) can only be 374 set to the non-default value by explicitly setting them to `false`: 375 376 ```console 377 $ docker build --rm=false . 378 ``` 379 380 #### Multi 381 382 You can specify options like `-a=[]` multiple times in a single command line, 383 for example in these commands: 384 385 ```console 386 $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash 387 388 $ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls 389 ``` 390 391 Sometimes, multiple options can call for a more complex value string as for 392 `-v`: 393 394 ```console 395 $ docker run -v /host:/container example/mysql 396 ``` 397 398 > **Note** 399 > 400 > Do not use the `-t` and `-a stderr` options together due to 401 > limitations in the `pty` implementation. All `stderr` in `pty` mode 402 > simply goes to `stdout`. 403 404 #### Strings and Integers 405 406 Options like `--name=""` expect a string, and they 407 can only be specified once. Options like `-c=0` 408 expect an integer, and they can only be specified once.