Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 111 ยท Getting Started

The Docker CLI

Learn how the Docker command line is organized: management commands versus legacy aliases, built-in help, formatting output, docker info and docker system df.

Docker has dozens of commands, and at first they look like a pile of unrelated words: run, ps, rmi, exec, prune. In fact the CLI follows a clear structure, and once you see it you can guess most commands you have never typed. This lesson shows you that structure, how to get help without leaving the terminal, how to control what output looks like, and how to inspect the state of your Docker installation.

You will also learn the difference between the short commands in old tutorials (docker ps, docker rmi) and the newer grouped commands (docker container ls, docker image rm), so you can read any example you come across.

Command structure

Docker commands have the shape:

TEXT
docker [GLOBAL OPTIONS] COMMAND [OPTIONS] [ARGUMENTS]

Global options such as --context or --host come right after docker. The command comes next, then options for that command, then its arguments (an image name, container names, and so on). Options go before the image name in docker run, because everything after the image is the command to run inside the container:

CONSOLE
$ docker run --rm -e GREETING=hi alpine:3.22 env
...
GREETING=hi
...
$ docker run --rm alpine:3.22 -e GREETING=hi env
docker: Error response from daemon: ... exec: "-e": executable file not found in $PATH

The first line passes -e to Docker. In the second, -e GREETING=hi env comes after the image and is treated as the command to run in the container. This is one of the most common beginner mistakes.

Management commands and legacy aliases

Early versions of Docker had a flat list of about forty commands. As the list grew, Docker grouped related commands under management commands, one per kind of object:

Management command Manages Examples
docker container containers ls, run, stop, rm, logs, exec
docker image images ls, pull, rm, history, inspect, prune
docker volume volumes create, ls, rm, prune
docker network networks create, ls, connect, rm
docker system the daemon as a whole df, info, prune, events
docker builder / docker buildx builds build, prune, ls
docker context CLI-to-daemon connections ls, use, create
docker compose multi-container apps up, down, ps, logs

The grouped form is docker <object> <verb>. The old flat commands still work as aliases, and the most common ones are what people actually type:

Short form (common) Full form
docker ps docker container ls
docker run docker container run
docker rm docker container rm
docker images docker image ls
docker rmi docker image rm
docker pull docker image pull
docker exec docker container exec

You can confirm that they are the same command: docker ps --help lists its aliases.

CONSOLE
$ docker ps --help
Usage:  docker ps [OPTIONS]

List containers

Aliases:
  docker container ls, docker container list, docker container ps, docker ps
...

Neither form is deprecated, so use whichever you prefer. This tutorial uses the short forms for the everyday commands (docker run, docker ps, docker images) because they are shorter and appear in nearly every guide, and the grouped form where it is clearer (docker volume ls, docker network create). In scripts, the grouped form is more explicit and easier to read for newcomers.

Getting help

Docker documents itself well. There is a built-in help at every level, and it always matches the exact version you have installed.

docker --help (or just docker) prints the overview. In Docker 29 it begins with the commonly used commands, followed by the management commands:

CONSOLE
$ docker --help
Usage:  docker [OPTIONS] COMMAND

A self-sufficient runtime for containers

Common Commands:
  run         Create and run a new container from an image
  exec        Execute a command in a running container
  ps          List containers
  build       Build an image from a Dockerfile
  bake        Build from a file
  pull        Download an image from a registry
  push        Upload an image to a registry
  images      List images
  login       Authenticate to a registry
  logout      Log out from a registry
  search      Search Docker Hub for images
  version     Show the Docker version information
  info        Display system-wide information

Management Commands:
  builder     Manage builds
  buildx*     Docker Buildx
  compose*    Docker Compose
  container   Manage containers
  context     Manage contexts
  image       Manage images
  network     Manage networks
  system      Manage Docker
  volume      Manage volumes
  ...

(Shortened: your installation lists more entries, including plugins from Docker Desktop. The asterisk marks a plugin, a separate program such as Compose or Buildx that docker finds and runs for you.)

For one object type, add its name:

CONSOLE
$ docker container --help
Usage:  docker container COMMAND

Manage containers

Commands:
  attach      Attach local standard input, output, and error streams to a running container
  commit      Create a new image from a container's changes
  cp          Copy files/folders between a container and the local filesystem
  create      Create a new container
  diff        Inspect changes to files or directories on a container's filesystem
  exec        Execute a command in a running container
  ...
  logs        Fetch the logs of a container
  ls          List containers
  ...

And for one command, put --help after it. docker run --help is long, because docker run has more than a hundred options, but it is the authoritative list:

CONSOLE
$ docker run --help
Usage:  docker run [OPTIONS] IMAGE [COMMAND] [ARG...]

Create and run a new container from an image

Aliases:
  docker container run, docker run

Options:
      --add-host list                    Add a custom host-to-IP mapping
                                         (host:ip)
...

Pipe it to a pager or grep when you search for an option: docker run --help | grep -i memory. An unknown command gives a short message pointing you back to the help:

CONSOLE
$ docker foo
docker: unknown command: docker foo

Run 'docker --help' for more information

If docker COMMAND --help and an online tutorial disagree, trust --help. Docker removes and renames options over the years, and what you see in the terminal is correct for your version.

Names, IDs and short IDs

Most commands that act on one container or image accept either its name or its ID. IDs are long hexadecimal strings, but you only need to type enough of the start to be unambiguous, and the CLI usually shows a 12-character version:

CONSOLE
$ docker run -d --name web nginx:alpine
7f9adba84cbdbc4fb9d27d3e66534dbbb6f0c61fda85310e18aa942fdfe270f1
$ docker stop 7f9a
7f9a
$ docker rm web
web

The -d flag (detached) is explained in the next lessons; it prints the full 64-character ID. Notice that docker stop 7f9a works with the first four characters, and it echoes back exactly what you typed. Names are friendlier and are what you should use in scripts and documents. Container names must be unique on a host; a second container with the same name is refused:

CONSOLE
$ docker run --name web -d nginx:alpine
docker: Error response from daemon: Conflict. The container name "/web" is already in use by container "69db14cb54f2...". You have to remove (or rename) that container to be able to reuse that name.

Controlling the output

By default Docker prints tables for people. For scripts, and for showing exactly what you want, there are three useful tools.

Quiet mode (-q, --quiet) prints only IDs, one per line, which is ideal as input to another command:

CONSOLE
$ docker ps -q --filter name=web
7f9adba84cbd

Filters (--filter key=value, repeatable) narrow a list: --filter status=exited, --filter name=web, --filter ancestor=nginx:alpine for containers; --filter dangling=true for images.

Formats (--format) take a Go template. Placeholders such as {{.Names}} insert fields. With the keyword table you get a table with headings; without it, plain lines:

CONSOLE
$ docker ps --filter name=web --format '{{.Names}}: {{.Status}}'
web: Up 1 second
$ docker image ls alpine:3.22 --format '{{.Repository}}:{{.Tag}} {{.Size}}'
alpine:3.22 12.9MB
$ docker ps --filter name=web --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
NAMES   IMAGE          STATUS
web     nginx:alpine   Up 1 second

Every command that lists or inspects things understands --format. The special value json prints each record as JSON, which you can feed to jq. You will use formats heavily in Listing and Inspecting.

A related shortcut: docker version --format '{{.Server.Version}}' and docker info --format '{{.ServerVersion}}' extract a single value for use in scripts.

docker info: the state of your installation

docker info reports configuration and counters for the daemon. You saw pieces of it in Installing Docker. The important lines in the server section:

CONSOLE
$ docker info
...
Server:
 Containers: 14
  Running: 7
  Paused: 0
  Stopped: 7
 Images: 44
 Server Version: 29.8.1
 Storage Driver: overlayfs
  driver-type: io.containerd.snapshotter.v1
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 nvidia runc
 Default Runtime: runc
 Security Options:
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.18.54.1-microsoft-standard-WSL2
 Operating System: Docker Desktop (containerized)
 OSType: linux
 Architecture: x86_64
 CPUs: 6
 Total Memory: 11.63GiB
 Docker Root Dir: /var/lib/docker
...

(Counts and hardware values are from the author's machine and will differ on yours.) What to look for:

  • Containers / Images give a quick sense of how much is on the host.
  • Storage Driver is how layers are stored (overlayfs here, with containerd's image store; overlay2 on older installations).
  • Logging Driver defaults to json-file, which stores container output as files on the host (see Logging and Monitoring).
  • Cgroup Version tells you which resource-limit mechanism the host uses.
  • Plugins lists the available network, volume and logging drivers.
  • Swarm: inactive means Docker's built-in orchestrator is not enabled.
  • CPUs and Total Memory are what containers can use (on Docker Desktop they are set in the application's settings, because the VM has its own allocation).

On a Linux server Docker Root Dir is where everything is stored on disk, so that is the partition to watch when space runs low. If docker info ends with warnings (for example about missing cgroup limit support), read them; they point to real configuration gaps.

docker system df: where did my disk space go?

Docker never deletes anything on its own, so disk usage grows quietly: stopped containers, old image versions, unused volumes, and build cache. docker system df summarizes it:

CONSOLE
$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          27        12        13.12GB   553.4MB (4%)
Containers      14        6         6.148GB   1.954MB (0%)
Local Volumes   13        10        1.335GB   306.4MB (22%)
Build Cache     92        0         20.53GB   20.11GB

(These are real numbers from a busy development machine; yours will be smaller.) Each row means:

  • TOTAL is how many objects exist; ACTIVE is how many are in use (an image used by a container, a volume attached to a container).
  • SIZE is the disk they occupy.
  • RECLAIMABLE is what removing the unused ones would free.

On this machine the build cache is the biggest item and almost all of it is reclaimable, which is typical for developers who build images often. Add -v for a per-object listing, which tells you which exact images or volumes are large. You will turn this knowledge into action in Cleaning Up.

Be careful with the prune family of commands (docker system prune, docker volume prune). They delete objects that are not currently used, and "not currently used" is a looser idea than "not needed". A volume holding a stopped database's data counts as unused. Read the confirmation prompt before you press y.

Everyday command map

A quick map of the commands you will use most in the coming lessons:

Task Command
Run a container docker run [-d] [--name N] IMAGE
List running / all containers docker ps / docker ps -a
Stop / start / remove docker stop N, docker start N, docker rm N
See output docker logs N
Run a command in a running container docker exec -it N sh
List / pull / remove images docker images, docker pull IMAGE, docker rmi IMAGE
Low-level details docker inspect N
Disk usage docker system df

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How are docker ps and docker container ls related?

    docker ps is the classic short form of docker container ls. Both work, and docker ps --help lists the aliases.
  2. 2. What is wrong with docker run alpine:3.22 -e NAME=Ada env?

    Docker options must come before the image name. Anything after the image is the command and its arguments, so the container tries to execute a program named -e.
  3. 3. Which option prints only container IDs, one per line, so another command can use them?

    -q prints just IDs, which is useful in scripts, for example to pass them to docker rm.
  4. 4. You want a one-line status like web: Up 1 second for a container. What do you use?

    --format takes a Go template whose placeholders are the column fields, such as .Names and .Status.
  5. 5. What does the RECLAIMABLE column of docker system df tell you?

    Reclaimable is the space held by objects that nothing currently uses, such as unreferenced images, stopped containers, unused volumes and old build cache.

Summary

  • Docker commands follow docker [global options] COMMAND [options] [arguments]; options for docker run go before the image name.
  • Management commands group by object (docker container, docker image, docker volume, docker network, docker system); the old flat commands such as docker ps and docker rmi remain valid aliases.
  • Use docker --help, docker COMMAND --help and docker COMMAND SUBCOMMAND --help; they always match your installed version.
  • Containers and images can be referred to by name or by a unique prefix of their ID.
  • -q, --filter and --format control and narrow the output; --format takes Go templates.
  • docker info shows the daemon's configuration; docker system df shows what uses disk space and how much is reclaimable.

Next: Running Containers