ctr

A development/debug CLI for the daemon. Not stable, not user-friendly by design — its purpose is to give maintainers a thin wrapper over the gRPC API for poking individual operations during development.

Purpose

ctr exists to:

• Issue ad-hoc gRPC calls without writing Go code.
• Verify daemon behavior in CI integration tests and make integration.
• Provide quick reproductions for bug reports.

For real workloads, use nerdctl, crictl, Docker, or the Kubernetes kubelet — all of which talk to containerd through more polished interfaces.

Directory layout

cmd/ctr/
├── main.go        # 20 lines; calls app.New
├── app/           # urfave/cli app builder
└── commands/      # one subdirectory per command group
    ├── containers/    # ctr containers ls / create / rm
    ├── content/       # ctr content fetch / get / ingest / list
    ├── events/        # ctr events
    ├── images/        # ctr images pull / push / list / mount / convert
    ├── leases/        # ctr leases
    ├── namespaces/    # ctr namespaces
    ├── plugins/       # ctr plugins ls
    ├── pprof/         # ctr pprof against the debug socket
    ├── run/           # ctr run (combines image + container + task)
    ├── sandbox/       # ctr sandbox
    ├── snapshots/     # ctr snapshots ls / mounts / rm
    ├── tasks/         # ctr tasks ls / start / kill / delete / exec / metrics / ...
    ├── version/       # ctr version
    └── ... (oci, info, install, deprecations, ...)

Each subdirectory exposes a Command (or Commands) variable that the app package wires into the cli tree.

How it talks to the daemon

ctr constructs a client.Client from client/ and uses the same Go API any other embedder would. Most commands look like:

ctx, cancel := commands.AppContext(c)
defer cancel()
client, err := commands.NewClient(c)
... use client.Containers().Get(...), client.Pull(...), etc.

The --address flag controls the socket; --namespace (or $CONTAINERD_NAMESPACE) sets the namespace.

Commands by frequency in tests

The Make integration tests and CRI integration scripts heavily use:

• ctr image pull and ctr image rm
• ctr run --rm (one-shot container)
• ctr task ls, ctr task kill, ctr task metrics
• ctr content for inspecting blobs
• ctr namespaces ls/create/remove
• ctr plugins ls (sanity-check that plugins loaded)

Auto-completion

contrib/autocomplete/ctr provides bash completion; a zsh variant is also available. They are sourced from the user's shell init.

Entry points for modification

• New command: add a subdirectory under cmd/ctr/commands/<group> and register it in cmd/ctr/app/.
• New flag: each command file exposes Flags []cli.Flag.
• New output format: most listing commands take --format and pipe through Go's text/template.