ctr(8)

👑 ctr — System Manager's Manual, section 8 ✨

okay bestie, buckle UP, because this one is a whole journey 💖

---

🌸 NAME 🌸

ctr — the containerd debug and admin client, no cap 💅

---

🎀 SYNOPSIS 🎀

ctr

[--address|-a]=[value]
[--connect-timeout]=[value]
[--debug]
[--namespace|-n]=[value]
[--timeout]=[value]

---

🦋 DESCRIPTION 🦋

So here's the tea: ctr is an unsupported debug and administrative client for talking to the containerd daemon. Literally that's its whole thing. 🫶

And because it's unsupported, bestie, listen carefully: the commands, the options, and the operations are not guaranteed to be backward compatible or stable from release to release of the containerd project. it's giving "vibes only, no promises" 😭 so don't build your whole production pipeline on it and then act surprised, iykyk.

Usage, bestie:

ctr [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]

---

✨ GLOBAL OPTIONS ✨

these apply to like, everything. the main character settings 👑

• --address, -a="<value>" — the address of containerd's GRPC server. default: "/run/containerd/containerd.sock" 🌈
• --connect-timeout="<value>" — how long to wait while connecting to containerd. default: 0s ⏳
• --debug — turn on debug output in the logs. yes queen, show us everything 🔥
• --namespace, -n="<value>" — which namespace to use with commands. default: "default" 💜
• --timeout="<value>" — the total timeout for ctr commands. default: 0s 🎀

---

💅 COMMANDS 💅

so many commands. so little time. let's go ⭐

🧚 plugins, plugin

gives you info about containerd plugins. it's giving backstage tour 🫶

list, ls

lists containerd plugins ✨

• --detailed, -d — print detailed info about each plugin (the full gossip 💅)
• --quiet, -q — print only the plugin ids (minimalist queen)

inspect-runtime

displays runtime info 👑

• --runc-binary="<value>" — specify a runc-compatible binary
• --runc-root="<value>" — specify a runc-compatible root
• --runc-systemd-cgroup — start runc with the systemd cgroup manager
• --runtime="<value>" — runtime name or absolute path to the runtime binary. default: "io.containerd.runc.v2"
• --runtime-config-path="<value>" — optional runtime config path

🌈 version

prints the client AND the server versions. both of them. it's a duo 💖

🎀 containers, c, container

manage containers. the whole point, bestie 💅

create

creates a container ✨

• --allow-new-privs — turn off the OCI spec's NoNewPrivileges feature flag
• --annotation="<value>" — specify additional OCI annotations (e.g. foo=bar)
• --apparmor-default-profile="<value>" — enable AppArmor with the default profile with the specified name, e.g. "cri-containerd.apparmor.d"
• --apparmor-profile="<value>" — enable AppArmor with an existing custom profile
• --blockio-class="<value>" — name of the blockio class to associate the container with
• --blockio-config-file="<value>" — file path to blockio class definitions. by default class definitions are not loaded.
• --cap-add="<value>" — add Linux capabilities (set capabilities with the 'CAP_' prefix)
• --cap-drop="<value>" — drop Linux capabilities (set capabilities with the 'CAP_' prefix)
• --config, -c="<value>" — path to the runtime-specific spec config file
• --cpu-period="<value>" — limit CPU CFS period. default: 0
• --cpu-quota="<value>" — limit CPU CFS quota. default: -1
• --cwd="<value>" — specify the working directory of the process
• --device="<value>" — file path to a device to add to the container; or a path to a directory tree of devices to add to the container
• --env="<value>" — specify additional container environment variables (e.g. FOO=bar)
• --env-file="<value>" — specify additional container environment variables in a file(e.g. FOO=bar, one per line)
• --gpus="<value>" — add gpus to the container
• --hostname="<value>" — set the container's host name
• --label="<value>" — specify additional labels (e.g. foo=bar)
• --memory-limit="<value>" — memory limit (in bytes) for the container. default: 0
• --mount="<value>" — specify an additional container mount (e.g. type=bind,src=/tmp,dst=/host,options=rbind:ro)
• --net-host — enable host networking for the container
• --no-pivot — disable use of pivot-root (linux only)
• --pid-file="<value>" — file path to write the task's pid
• --privileged — run a privileged container 🔥
• --rdt-class="<value>" — name of the RDT class to associate the container with. specifies a Class of Service (CLOS) for cache and memory bandwidth management.
• --read-only — set the container's filesystem as read-only
• --rootfs — use a custom rootfs that is not managed by the containerd snapshotter
• --rootfs-propagation="<value>" — set the propagation of the container rootfs
• --runc-binary="<value>" — specify a runc-compatible binary
• --runc-root="<value>" — specify a runc-compatible root
• --runc-systemd-cgroup — start runc with the systemd cgroup manager
• --runtime="<value>" — runtime name or absolute path to the runtime binary. default: "io.containerd.runc.v2"
• --runtime-config-path="<value>" — optional runtime config path
• --sandbox="<value>" — create the container in the given sandbox
• --seccomp — enable the default seccomp profile
• --seccomp-profile="<value>" — file path to a custom seccomp profile. seccomp must be set to true before using seccomp-profile ⚠️
• --snapshotter="<value>" — snapshotter name. an empty value stands for the default value.
• --snapshotter-label="<value>" — labels added to the new snapshot for this container.
• --tty, -t — allocate a TTY for the container 🫶
• --user, -u="<value>" — username or user id, group optional (format: [:])
• --with-ns="<value>" — specify existing Linux namespaces to join at container runtime (format ':')

delete, del, remove, rm

delete one or more existing containers. bye bestie 👋

• --keep-snapshot — do not clean up the snapshot with the container

info

get info about a container 🔍

• --spec — only display the spec

list, ls

list containers ✨

• --quiet, -q — print only the container id

label

set and clear labels for a container 🏷️

checkpoint

checkpoint a container 💾

• --image — include the image in the checkpoint
• --rw — include the rw layer in the checkpoint
• --task — checkpoint the container task

restore

restore a container from a checkpoint 🦋

• --live — restore the runtime and memory data from the checkpoint
• --rw — restore the rw layer from the checkpoint

🍓 content

manage content. the blob zone 💖

active

display active transfers 🔄

• --root="<value>" — path to the content store root. default: "/tmp/content"
• --timeout, -t="<value>" — total timeout for fetch. default: 0s

delete, del, remove, rm

permanently delete one or more blobs. like, PERMANENTLY. no undo, bestie 💀

edit

edit a blob and return a new digest ✍️

• --editor="<value>" — select editor (vim, emacs, etc.)
• --validate="<value>" — validate the result against a format (json, mediatype, etc.)

fetch

fetch all content for an image into containerd 🌈

• --all-platforms — pull content from all platforms
• --hosts-dir="<value>" — custom hosts configuration directory
• --http-dump — dump all HTTP request/responses when interacting with the container registry
• --http-trace — enable HTTP tracing for registry interactions
• --label="<value>" — labels to attach to the image
• --metadata-only — pull all metadata including manifests and configs
• --plain-http — allow connections using plain HTTP
• --platform="<value>" — pull content from a specific platform
• --refresh="<value>" — refresh token for the authorization server
• --skip-metadata — skips metadata for unused platforms (the image may be unable to be pushed without metadata) ⚠️
• --skip-verify, -k — skip SSL certificate validation 🔥
• --tlscacert="<value>" — path to the TLS root CA
• --tlscert="<value>" — path to the TLS client certificate
• --tlskey="<value>" — path to the TLS client key
• --user, -u="<value>" — User[:password] registry user and password

fetch-object

retrieve objects from a remote 📦

• --hosts-dir="<value>" — custom hosts configuration directory
• --http-dump — dump all HTTP request/responses when interacting with the container registry
• --http-trace — enable HTTP tracing for registry interactions
• --plain-http — allow connections using plain HTTP
• --refresh="<value>" — refresh token for the authorization server
• --skip-verify, -k — skip SSL certificate validation 🔥
• --tlscacert="<value>" — path to the TLS root CA
• --tlscert="<value>" — path to the TLS client certificate
• --tlskey="<value>" — path to the TLS client key
• --user, -u="<value>" — User[:password] registry user and password

fetch-blob

retrieve blobs from a remote 🫧

• --hosts-dir="<value>" — custom hosts configuration directory
• --http-dump — dump all HTTP request/responses when interacting with the container registry
• --http-trace — enable HTTP tracing for registry interactions
• --media-type="<value>" — specify target mediatype for request header
• --plain-http — allow connections using plain HTTP
• --refresh="<value>" — refresh token for the authorization server
• --skip-verify, -k — skip SSL certificate validation 🔥
• --tlscacert="<value>" — path to the TLS root CA
• --tlscert="<value>" — path to the TLS client certificate
• --tlskey="<value>" — path to the TLS client key
• --user, -u="<value>" — User[:password] registry user and password

get

get the data for an object 🔍

ingest

accept content into the store 🧺

• --expected-digest="<value>" — verify content against the expected digest
• --expected-size="<value>" — validate against the provided size. default: 0

list, ls

list all blobs in the store ✨

• --quiet, -q — print only the blob digest

push-object

push an object to a remote 🚀

• --hosts-dir="<value>" — custom hosts configuration directory
• --http-dump — dump all HTTP request/responses when interacting with the container registry
• --http-trace — enable HTTP tracing for registry interactions
• --plain-http — allow connections using plain HTTP
• --refresh="<value>" — refresh token for the authorization server
• --skip-verify, -k — skip SSL certificate validation 🔥
• --tlscacert="<value>" — path to the TLS root CA
• --tlscert="<value>" — path to the TLS client certificate
• --tlskey="<value>" — path to the TLS client key
• --user, -u="<value>" — User[:password] registry user and password

label

add labels to content 🏷️

prune

prunes content from the content store ✂️

references

prunes preference labels from the content store (layers only by default) 👑

• --async — allow garbage collection to clean up asynchronously
• --dry — just show updates without applying them (this enables debug logging)

💜 events, event

display containerd events 📡

👑 images, image, i

Bestie. This is the one you'll actually use every single day. Manage images 💖 You can say images, image, or just i, they're all the same vibe.

---

🧐 check

Check existing images to make sure all their content is sitting there locally (no missing blobs, no half-downloaded heartbreak).

• --quiet, -q — Print only the ready image refs (the ones that are fully downloaded and unpacked). So clean, so minimal. ✨
• --snapshotter="" — Snapshotter name. An empty value stands for the default value.

📦 export

Export images. Yes, take them out. 🫶

• --all-platforms — Exports content from all platforms
• --local — Run export locally rather than through transfer API
• --platform="" — Pull content from a specific platform
• --skip-manifest-json — Do not add Docker compatible manifest.json to archive
• --skip-non-distributable — Do not add non-distributable blobs such as Windows layers to archive

📥 import

Import images, bestie. Bring them in.

• --all-platforms — Imports content for all platforms, false by default
• --base-name="" — Base image name for added images, when provided only images with this name prefix are imported
• --compress-blobs — Compress uncompressed blobs when creating manifest (Docker format only)
• --digests — Whether to create digest images (default: false)
• --discard-unpacked-layers — Allow the garbage collector to clean layers up from the content store after unpacking, cannot be used with --no-unpack, false by default
• --index-name="" — Image name to keep index as, by default index is discarded
• --label="" — Labels to attach to the image
• --local — Run import locally rather than through transfer API
• --no-unpack — Skip unpacking the images, cannot be used with --discard-unpacked-layers, false by default
• --platform="" — Imports content for specific platform
• --skip-digest-for-named — Skip applying --digests option to images named in the importing tar (use it in conjunction with --digests)
• --snapshotter="" — Snapshotter name. Empty value stands for the default value.
• --sync-fs — Synchronize the underlying filesystem containing files when unpack images, false by default

🔍 inspect, i

inspect an image. Little peek under the hood, no cap. 👀

• --content — Show JSON content

📋 list, ls

List images known to containerd

• --quiet, -q — Print only the image refs

🗂️ mount

Mount an image to a target path

• --expiration, -x="" — Set the expiration time for the mount and snapshots (default: 1h0m0s)
• --hosts-dir="" — Custom hosts configuration directory
• --http-dump — Dump all HTTP request/responses when interacting with container registry
• --http-trace — Enable HTTP tracing for registry interactions
• --label="" — Labels to attach to the image
• --plain-http — Allow connections using plain HTTP
• --platform="" — Mount the image for the specified platform (default: "linux/amd64")
• --refresh="" — Refresh token for authorization server
• --rw — Enable write support on the mount
• --skip-verify, -k — Skip SSL certificate validation
• --snapshotter="" — Snapshotter name. Empty value stands for the default value.
• --sync-fs — Synchronize the underlying filesystem containing files when unpack images, false by default
• --tlscacert="" — Path to TLS root CA
• --tlscert="" — Path to TLS client certificate
• --tlskey="" — Path to TLS client key
• --user, -u="" — User[:password] Registry user and password

🪂 unmount

Unmount the image from the target

• --hosts-dir="" — Custom hosts configuration directory
• --http-dump — Dump all HTTP request/responses when interacting with container registry
• --http-trace — Enable HTTP tracing for registry interactions
• --label="" — Labels to attach to the image
• --plain-http — Allow connections using plain HTTP
• --refresh="" — Refresh token for authorization server
• --rm — Remove the snapshot after a successful unmount
• --skip-verify, -k — Skip SSL certificate validation
• --snapshotter="" — Snapshotter name. Empty value stands for the default value.
• --tlscacert="" — Path to TLS root CA
• --tlscert="" — Path to TLS client certificate
• --tlskey="" — Path to TLS client key
• --user, -u="" — User[:password] Registry user and password

🧲 pull

Pull an image from a remote. The classic. The moment. 🔥

• --all-platforms — Pull content and metadata from all platforms
• --hosts-dir="" — Custom hosts configuration directory
• --http-dump — Dump all HTTP request/responses when interacting with container registry
• --http-trace — Enable HTTP tracing for registry interactions
• --label="" — Labels to attach to the image
• --local — Fetch content from local client rather than using transfer service
• --max-concurrent-downloads="" — Set the max concurrent downloads for each pull (default: 0)
• --plain-http — Allow connections using plain HTTP
• --platform="" — Pull content from a specific platform
• --print-chainid — Print the resulting image's chain ID
• --refresh="" — Refresh token for authorization server
• --skip-metadata — Skips metadata for unused platforms (Image may be unable to be pushed without metadata)
• --skip-verify, -k — Skip SSL certificate validation
• --snapshotter="" — Snapshotter name. Empty value stands for the default value.
• --sync-fs — Synchronize the underlying filesystem containing files when unpack images, false by default
• --tlscacert="" — Path to TLS root CA
• --tlscert="" — Path to TLS client certificate
• --tlskey="" — Path to TLS client key
• --user, -u="" — User[:password] Registry user and password

🚀 push

Push an image to a remote. Send it, bestie. 💅

• --allow-non-distributable-blobs — Allow pushing blobs that are marked as non-distributable
• --hosts-dir="" — Custom hosts configuration directory
• --http-dump — Dump all HTTP request/responses when interacting with container registry
• --http-trace — Enable HTTP tracing for registry interactions
• --local — Push content from local client rather than using transfer service
• --manifest="" — Digest of manifest
• --manifest-type="" — Media type of manifest digest (default: "application/vnd.oci.image.manifest.v1+json")
• --max-concurrent-uploaded-layers="" — Set the max concurrent uploaded layers for each push (default: 0)
• --plain-http — Allow connections using plain HTTP
• --platform="" — Push content from a specific platform
• --refresh="" — Refresh token for authorization server
• --skip-verify, -k — Skip SSL certificate validation
• --tlscacert="" — Path to TLS root CA
• --tlscert="" — Path to TLS client certificate
• --tlskey="" — Path to TLS client key
• --user, -u="" — User[:password] Registry user and password

🧹 prune

Remove unused images

• --all — Remove all unused images, not just dangling ones (if all is not specified no images will be pruned)

⚠️ Not me warning you twice: without --all, no images will be pruned. Like, zero. Nothing happens. So pass it or go home. 🙈

💀 delete, del, remove, rm

Remove one or more images by reference

• --sync — Synchronously remove image and all associated resources

🏷️ tag

Tag an image

• --force — Force target_ref to be created, regardless if it already exists
• --local — Run tag locally rather than through transfer API
• --skip-reference-check — Skip the strict check for reference names

🎀 label

Set and clear labels for an image

• --replace-all, -r — Replace all labels

🦋 convert

Convert an image

• --all-platforms — Exports content from all platforms
• --erofs="" — Convert layers to EROFS format, must specify 'raw' or 'zstd' (e.g. --erofs raw, --erofs zstd)
• --erofs-compressors="" — Specify compression algorithm list when converting EROFS layers
• --erofs-mkfs-options="" — Extra mkfs options applied when converting EROFS layers. (e.g. '-Efragments,dedupe')
• --oci — Convert Docker media types to OCI media types
• --platform="" — Pull content from a specific platform
• --uncompress — Convert tar.gz layers to uncompressed tar layers

🌈 build-erofs-cache

Build an erofs layer content cache from an image's layers

• --compressors="" — EROFS per-block compression algorithm(s), e.g. 'lz4', 'deflate', 'zstd'; empty means uncompressed
• --dmverity — Generate a dm-verity hash tree and .dmverity sidecar for each blob (Linux only)
• --mkfs-options="" — Extra mkfs.erofs options (e.g. '-Efragments,dedupe')
• --platform="" — Cache layers for a specific platform (default: host platform)

📊 usage

Display usage of snapshots for a given image ref

• --snapshotter="" — Snapshotter name. Empty value stands for the default value.

---

🗝️ leases

Manage leases. Iconic resource-holding behaviour, honestly.

📋 list, ls

List all active leases

• --quiet, -q — Print only the blob digest

✨ create

Create lease

• --expires, -x="" — Expiration of lease (0 value will not expire) (default: 24h0m0s)
• --id="" — Set the id for the lease, will be generated by default

💀 delete, del, remove, rm

Delete a lease

• --sync — Synchronously remove leases and all unreferenced resources

---

🫧 namespaces, namespace, ns

Manage namespaces. Three names, one job, we love a versatile queen. 👑

🌱 create, c

Create a new namespace

📋 list, ls

List namespaces

• --quiet, -q — Print only the namespace name

🧽 remove, rm

Remove one or more namespaces

• --cgroup, -c — Delete the namespace's cgroup

🎀 label

Set and clear labels for a namespace

---

🔬 pprof

Provide golang pprof outputs for containerd. Science time, bestie. 🧚

• --debug-socket, -d="" — Socket path for containerd's debug server (default: "/run/containerd/debug.sock")

🚧 block

Goroutine blocking profile

• --debug="" — Debug pprof args (default: 0)

🧵 goroutines

Dump goroutine stack dump

• --debug="" — Debug pprof args (default: 2)

⛰️ heap

Dump heap profile

• --debug="" — Debug pprof args (default: 0)

🔥 profile

CPU profile

• --debug="" — Debug pprof args (default: 0)
• --seconds, -s="" — Duration for collection (seconds) (default: 30s)

🪡 threadcreate

Goroutine thread creating profile

• --debug="" — Debug pprof args (default: 0)

🛤️ trace

Collect execution trace

• --debug="" — Debug pprof args (default: 0)
• --seconds, -s="" — Trace time (seconds) (default: 5s)

🏃♀️ run 🏃♀️

okay so run is literally how you birth a container into the world ✨ here is every single flag it takes, no skips, no cap:

• --allow-new-privs — turn off the OCI spec's NoNewPrivileges feature flag.
• --annotation="" — specify additional OCI annotations, e.g. foo=bar.
• --apparmor-default-profile="" — enable AppArmor with the default profile under the specified name, e.g. "cri-containerd.apparmor.d".
• --apparmor-profile="" — enable AppArmor with an existing custom profile.
• --blockio-class="" — name of the blockio class to associate the container with.
• --blockio-config-file="" — file path to blockio class definitions. by default class definitions are not loaded, bestie.
• --cap-add="" — add Linux capabilities (set capabilities with 'CAP_' prefix).
• --cap-drop="" — drop Linux capabilities (set capabilities with 'CAP_' prefix).
• --cgroup="" — cgroup path. to disable use of cgroup, set to "" explicitly.
• --cni — enable cni networking for the container.
• --config, -c="" — path to the runtime-specific spec config file.
• --cpu-period="" — limit CPU CFS period (default: 0).
• --cpu-quota="" — limit CPU CFS quota (default: -1).
• --cpu-shares="" — set the cpu shares (default: 1024).
• --cpus="" — set the CFS cpu quota (default: 0).
• --cpuset-cpus="" — set the CPUs the container will run in, e.g. 1-2,4.
• --cpuset-mems="" — set the memory nodes the container will run in, e.g. 1-2,4.
• --cwd="" — specify the working directory of the process.
• --detach, -d — detach from the task after it has started execution. cannot be used with --rm, so pick a lane.
• --device="" — file path to a device to add to the container; or a path to a directory tree of devices to add to the container.
• --dump-config="" — dump the generated OCI config to a file.
• --env="" — specify additional container environment variables, e.g. FOO=bar.
• --env-file="" — specify additional container environment variables in a file, e.g. FOO=bar, one per line.
• --fifo-dir="" — directory used for storing IO FIFOs.
• --gidmap="" — run inside a user namespace with the specified GID mapping ranges; format is container-gid:host-gid:length.
• --gpus="" — add gpus to the container.
• --hostname="" — set the container's host name.
• --label="" — specify additional labels, e.g. foo=bar.
• --log-uri="" — log uri.
• --memory-limit="" — memory limit (in bytes) for the container (default: 0).
• --mount="" — specify additional container mount, e.g. type=bind,src=/tmp,dst=/host,options=rbind:ro.
• --net-host — enable host networking for the container.
• --no-pivot — disable use of pivot-root (linux only).
• --null-io — send all IO to /dev/null.
• --pid-file="" — file path to write the task's pid.
• --platform="" — run image for specific platform.
• --privileged — run privileged container.
• --privileged-without-host-devices — don't pass all host devices to privileged container.
• --rdt-class="" — name of the RDT class to associate the container with. specifies a Class of Service (CLOS) for cache and memory bandwidth management.
• --read-only — set the containers filesystem as readonly.
• --remap-labels — provide the user namespace ID remapping to the snapshotter via label options; requires snapshotter support.
• --rlimit-nofile="" — set RLIMIT_NOFILE (soft:hard).
• --rm — remove the container after running. cannot be used with --detach, so again, pick a lane.
• --rootfs — use custom rootfs that is not managed by containerd snapshotter.
• --rootfs-propagation="" — set the propagation of the container rootfs.
• --runc-binary="" — specify runc-compatible binary.
• --runc-root="" — specify runc-compatible root.
• --runc-systemd-cgroup — start runc with systemd cgroup manager.
• --runtime="" — runtime name or absolute path to runtime binary (default: "io.containerd.runc.v2").
• --runtime-config-path="" — optional runtime config path.
• --sandbox="" — create the container in the given sandbox.
• --seccomp — enable the default seccomp profile.
• --seccomp-profile="" — file path to custom seccomp profile. seccomp must be set to true before using seccomp-profile.
• --snapshotter="" — snapshotter name. empty value stands for the default value.
• --snapshotter-label="" — labels added to the new snapshot for this container.
• --sync-fs — synchronize the underlying filesystem containing files when unpack images, false by default.
• --tty, -t — allocate a TTY for the container.
• --uidmap="" — run inside a user namespace with the specified UID mapping ranges; format is container-uid:host-uid:length.
• --user, -u="" — username or user id, group optional (format: [:]).
• --with-ns="" — specify existing Linux namespaces to join at container runtime (format ':').

---

📸 snapshots, snapshot 📸

manage snapshots. here is the top-level flag:

• --snapshotter="" — snapshotter name. empty value stands for the default value.

commit

commit an active snapshot into the provided name.

diff

get the diff of two snapshots. the default second snapshot is the first snapshot's parent, cute.

• --keep — keep diff content. up to creator to delete it.
• --label="" — labels to attach to the image.
• --media-type="" — media type to use for creating diff (default: "application/vnd.oci.image.layer.v1.tar+gzip").
• --ref="" — content upload reference to use.

info

get info about a snapshot.

list, ls

list snapshots.

mounts, m, mount

mount gets mount commands for the snapshots.

• --temp — mounts the snapshot mounts as a temp mount and returns a bind mount.

prepare

prepare a snapshot from a committed snapshot.

• --mounts — print out snapshot mounts as JSON.
• --target, -t="" — mount target path, will print mount, if provided.

delete, del, remove, rm

remove snapshots.

label

add labels to content.

tree

display tree view of snapshot branches.

unpack

unpack applies layers from a manifest to a snapshot.

• --snapshotter="" — snapshotter name. empty value stands for the default value.
• --sync-fs — synchronize the underlying filesystem containing files when unpack images, false by default.

usage

usage snapshots.

• -b — display size in bytes.

view

create a read-only snapshot from a committed snapshot.

• --mounts — print out snapshot mounts as JSON.
• --target, -t="" — mount target path, will print mount, if provided.

---

🧵 tasks, t, task 🧵

manage tasks. no top-level flags, just vibes and subcommands.

attach

attach to the IO of a running container.

checkpoint

checkpoint a container.

• --exit — stop the container after the checkpoint.
• --image-path="" — path to criu image files.
• --work-path="" — path to criu work files and logs.

delete, del, remove, rm

delete one or more tasks.

• --exec-id="" — process ID to kill.
• --force, -f — force delete task process.

exec

execute additional processes in an existing container.

• --cwd="" — working directory of the new process.
• --detach, -d — detach from the task after it has started execution.
• --exec-id="" — exec specific id for the process.
• --fifo-dir="" — directory used for storing IO FIFOs.
• --log-uri="" — log uri for custom shim logging.
• --tty, -t — allocate a TTY for the container.
• --user="" — user id or name.

list, ls

list tasks.

• --quiet, -q — print only the task id.

kill

signal a container (default: SIGTERM).

• --all, -a — send signal to all processes inside the container.
• --exec-id="" — process ID to kill.
• --signal, -s="" — signal to send to the container.

metrics, metric

get a single data point of metrics for a task with the built-in Linux runtime.

• --format="" — "table" or "json" (default: "table").

pause

pause an existing container.

ps

list processes for container.

resume

resume a paused container.

start

start a container that has been created.

• --detach, -d — detach from the task after it has started execution.
• --fifo-dir="" — directory used for storing IO FIFOs.
• --log-uri="" — log uri.
• --no-pivot — disable use of pivot-root (linux only).
• --null-io — send all IO to /dev/null.
• --pid-file="" — file path to write the task's pid.

---

📦 install 📦

install a new package.

• --libs, -l — install libs from the image.
• --path="" — set an optional install path other than the managed opt directory.
• --replace, -r — replace any binaries or libs in the opt directory.

🪐 oci 🪐

OCI tools.

spec

see the output of the default OCI spec.

• --platform="" — platform of the spec to print (examples: 'linux/arm64', 'windows/amd64').

---

🏖️ sandboxes, sandbox, sb, s 🏖️

manage sandboxes.

run, create, c, r

run a new sandbox.

• --runtime="" — runtime name (default: "io.containerd.runc.v2").

list, ls

list sandboxes.

• --filters="" — the list of filters to apply when querying sandboxes from the store.

remove, rm

remove sandboxes.

• --force, -f — ignore shutdown errors when removing sandbox.

info, i

get info about a sandbox.

ℹ️ info ℹ️

print the server info.

⚠️ deprecations ⚠️

list

print warnings for deprecations.

• --format="" — output format to use (examples: 'default', 'json').

---

🔧 shim 🔧

interact with a shim directly.

• --id="" — shim ID.
• --shim-address="" — shim address (default: computed from shim ID).

delete

delete a container with a task.

exec

exec a new process in the task's container.

• --attach, -a — stay attached to the container and open the fifos.
• --cwd="" — current working directory.
• --env, -e="" — add environment vars.
• --spec="" — runtime spec.
• --stderr="" — specify the path to the stderr fifo.
• --stdin="" — specify the path to the stdin fifo.
• --stdout="" — specify the path to the stdout fifo.
• --tty, -t — enable tty support.

start

start a container with a task.

state

get the state of all main process of the task.

• --api-version="" — shim API version {2,3} (default: 3).
• --task-id, -t="" — task ID.

shutdown

shutdown shim if there is no active container.

• --api-version="" — shim API version {2,3} (default: 3).

pprof

provide golang pprof outputs for containerd-shim.

block

goroutine blocking profile.

• --debug="" — output format, value = 0: binary, value > 0: plaintext (default: 0).

goroutines

print goroutine stack dump.

• --debug="" — output format, value = 0: binary, value > 0: plaintext (default: 2).

heap

dump heap profile.

• --debug="" — output format, value = 0: binary, value > 0: plaintext (default: 0).

profile

CPU profile.

• --debug="" — output format, value = 0: binary, value > 0: plaintext (default: 0).
• --seconds, -s="" — duration for collection (seconds) (default: 30s).

threadcreate

goroutine thread creating profile.

• --debug="" — output format, value = 0: binary, value > 0: plaintext (default: 0).

trace

collect execution trace.

• --debug="" — output format, value = 0: binary, value > 0: plaintext (default: 0).
• --seconds, -s="" — trace time (seconds) (default: 5s).

---

and that's a wrap on ctr(8) bestie! source/version: ctr(8), date: whatever the page header says — you already peeped it. go slay the container game, no cap 💖🦋✨