playbook/antigravity-awesome-skills/skills/apple-container/references/commands.md

container — Complete CLI Command Reference

Full command/flag reference for Apple's container CLI (repo apple/container), invoked as container ... on Apple-silicon macOS. Flags, defaults, aliases, and behavior are taken from the swift-argument-parser declarations in Sources/ContainerCommands/ (source of truth) and docs/command-reference.md; on conflicts the source wins.

Not Docker. The CLI is deliberately Docker-like, but flags, defaults, and daemon model differ — do not assume Docker behavior carries over. Every container runs in its own lightweight VM; there is no shared daemon (per-user launchd services). Registry lives under the Image group, not top-level.

Conventions used below: a value of — in the Default column means "no default (unset / optional)". "flag" in the Value column means a boolean switch (no argument). [env: NAME] marks an environment-variable fallback. Command availability varies by macOS version — caveats are called out inline.

Version: this reference tracks the 1.0.0 release. Items marked (1.0.0+) were added after 0.7.1 — namely container cp, container export, container prune, container image prune, container registry list, container system version, and the whole container machine group (on 0.7.1 the registry group had only login/logout). Run container <group> --help to confirm what your installed build supports.

---

Table of Contents

• Global
• Container lifecycle
  • run · create · exec · start · stop · kill · delete / rm · list / ls · logs · inspect · stats · copy / cp · export · prune
• Images
  • build · image · pull · push · tag · save · load · inspect · list / ls · delete / rm · prune
• Registry
  • login · logout · list / ls
• Builder
  • start · status · stop · delete / rm
• System
  • start · stop · status · version · logs · df · dns · kernel set · property list
• Network (macOS 26+)
  • create · delete / rm · list / ls · inspect · prune
• Volume
  • create · delete / rm · list / ls · inspect · prune
• Machine
  • create · run · set · set-default · list / ls · inspect · logs · stop · delete / rm

---

Global

Root command: container — "A container platform for macOS".

container [--debug] [--version] [-h|--help] <command> [<args> ...]

Flag	Value	Default	Description
--debug	flag	false	Enable debug output. Applies to every command (composed via Flags.Logging). [env: CONTAINER_DEBUG] — setting the env var (any value) also enables debug.
--version	flag	—	Print CLI version (container CLI version …) and exit.
-h, --help	flag	—	Show help. On the bare root command, help is augmented with a PLUGINS: section.

Notes:

• There is no global -d short flag. --debug is long-only. -d is --detach on run/create/exec/machine run.
• --debug is accepted on essentially every subcommand (each command composes Flags.Logging), so it is omitted from the per-command tables below unless useful.
• The CLI refuses to run under Rosetta translation (it exits with an error telling you to disable Rosetta in your terminal). Apple silicon only.
• Most commands talk to the background API server. If it is not running you get an "XPC connection error" hint: "Ensure container system service has been started with container system start." Run container system start first.

Command groups

Top-level help organizes subcommands into groups: Container (lifecycle), Image (build, image, registry), Machine, Volume, and Other (builder, network, system). Group aliases:

Group	Alias	Note
container image	i	The plural images is only the help section header, not a command (container images errors with "plugin not found").
container registry	r	Nested under the Image group.
container machine	m
container volume	v
container network	n	macOS 26+ only (absent on macOS 15).
container system	s
container builder	(none)

Plugin passthrough

If the first argument is not a recognized subcommand (and does not start with -), the CLI treats it as a plugin invocation: it looks for an executable named container-<arg> and execvps into it, passing through all remaining arguments.

• Plugin search directories (in order): the user plugins dir under the install root, the app bundle's plugins/, and <install-root>/libexec/container/plugins/. Only plugins whose config declares isCLI are eligible.
• Requires the system services to be running (the plugin loader queries the API server). If they are not, you get: "Plugins are unavailable. Start the container system services and retry: container system start."
• If no matching plugin is found: "Plugin 'container-' not found." with the searched paths listed.
• An unknown token starting with - yields "unknown option '…'"; an empty token yields "unknown argument '…'".
• Before exec, SIGINT/SIGTERM handlers are reset to default so the plugin manages its own signals.

container myplugin --flag arg     # execs container-myplugin --flag arg

---

Container lifecycle

The following flag groups are shared (composed via @OptionGroup) across run, create, and — for the process subset — exec. They are defined once here and referenced by name.

Process options (run, create, exec):

Flag	Value	Default	Description
-e, --env	<key=value>	—	Set env var. key=value, or bare key to inherit from host. Repeatable.
--env-file	<path>	—	Read env vars from a file (key=value; ignores # comments and blank lines). Repeatable.
--gid	<gid>	—	Group ID for the process.
-i, --interactive	flag	false	Keep stdin open even if not attached.
-t, --tty	flag	false	Open a TTY for the process.
-u, --user	<user>	—	User for the process (format name | uid[:gid]).
--uid	<uid>	—	User ID for the process.
-w, --workdir, --cwd	<dir>	—	Initial working directory inside the container. (-w, --workdir, and --cwd are all accepted.)
--ulimit	<type>=<soft>[:<hard>]	—	Resource limit (RLIMIT_*, e.g. nofile=1024:2048). Repeatable. Part of the shared Process group, so it also parses on exec.

Resource options (run, create):

Flag	Value	Default	Description
-c, --cpus	<n>	—	Number of CPUs to allocate.
-m, --memory	<size>	—	Memory (1 MiB granularity); optional K/M/G/T/P suffix.

Management options (run, create):

Flag	Value	Default	Description
-a, --arch	<arch>	host arch (e.g. arm64)	Arch to use if the image is multi-arch.
--cap-add	<cap>	—	Add a Linux capability (CAP_NET_RAW, NET_RAW, or ALL). Repeatable.
--cap-drop	<cap>	—	Drop a Linux capability. Repeatable.
--cidfile	<path>	""	Write the container ID to this path.
-d, --detach	flag	false	Run detached from the process.
--dns	<ip>	—	DNS nameserver IP. Repeatable.
--dns-domain	<domain>	—	Default DNS domain.
--dns-option	<option>	—	DNS option. Repeatable.
--dns-search	<domain>	—	DNS search domain. Repeatable.
--entrypoint	<cmd>	—	Override the image entrypoint.
--init	flag	false	Run an init process that forwards signals and reaps zombies.
--init-image	<image>	—	Custom init image (customize boot-time behavior: VM daemons, eBPF filters, debugging init).
-k, --kernel	<path>	—	Custom kernel path (resolved to an absolute path).
-l, --label	<key=value>	—	Add a label. Repeatable.
--mount	<spec>	—	Add a mount (type=<>,source=<>,target=<>,readonly). Repeatable.
--name	<name>	—	Use this name as the container ID (auto-generated otherwise).
--network	<spec>	—	Attach to a network (<name>[,mac=XX:XX:XX:XX:XX:XX][,mtu=VALUE]). Repeatable.
--no-dns	flag	false	Do not configure DNS. Conflicts with any --dns* flag (validation error).
--os	<os>	linux	OS to use if the image is multi-OS.
-p, --publish	<spec>	—	Publish a port ([host-ip:]host-port:container-port[/protocol]). Repeatable.
--platform	<platform>	—	Platform for multi-platform images (os/arch[/variant]). Takes precedence over --os/--arch. [env: CONTAINER_DEFAULT_PLATFORM]
--publish-socket	<spec>	—	Publish a socket (host_path:container_path). Repeatable.
--read-only	flag	false	Mount the root filesystem read-only.
--rm, --remove	flag	false	Remove the container after it stops.
--rosetta	flag	false	Enable Rosetta in the container.
--runtime	<handler>	—	Runtime handler (default: container-runtime-linux).
--ssh	flag	false	Forward the SSH agent socket into the container.
--shm-size	<size>	—	Size of /dev/shm (e.g. 64M, 1G).
--tmpfs	<path>	—	Add a tmpfs mount at the given path. Repeatable.
-v, --volume	<spec>	—	Bind-mount a volume. Repeatable.
--virtualization	flag	false	Expose virtualization capabilities (requires host and guest support).

Registry options (run, create):

Flag	Value	Default	Description
--scheme	http|https|auto	auto	Scheme for registry connections. auto picks http for loopback / RFC-1918 / internal-DNS-domain hosts, else https.

Progress options (run, create): --progress <auto\|none\|ansi\|plain\|color> (default auto).

Image-fetch options (run, create): --max-concurrent-downloads <n> (default 3).

---

container run

Run a container from an image. If a command is given, it runs inside the container; otherwise the image's default command runs. Foreground by default; stdin stays closed unless -i.

container run [<options>] <image> [<arguments> ...]

Arguments: <image> (image name, required) · <arguments> (init-process args, captured for passthrough — everything after the image is forwarded verbatim).

Options: all Process + Resource + Management + Registry + Progress + Image-fetch groups above.

# interactive shell
container run -it ubuntu:latest /bin/bash
# detached web server with a name and a published port
container run -d --name web -p 8080:80 nginx:latest
# env + resource limits
container run -e NODE_ENV=production --cpus 2 --memory 1G node:18
# fixed MAC on the default network
container run --network default,mac=02:42:ac:11:00:02 ubuntu:latest
# reap zombies / forward signals
container run --init ubuntu:latest my-app

Notes: on non-detached, non-TTY runs, pressing Ctrl-C 3× force-exits. --rm removes the container after it exits. On error the partially-created container is deleted.

---

container create

Create a container from an image without starting it. Same Process/Resource/Management/ Registry/Progress/Image-fetch flags as run; the container is left stopped.

container create [<options>] <image> [<arguments> ...]

Arguments: <image> (required) · <arguments> (init-process args, passthrough).

Options: identical to container run.

container create --name web -p 8080:80 nginx:latest
container start web

---

container exec

Run a command inside a running container. Uses the Process options group.

container exec [-d] [<process options>] <container-id> <arguments> ...

Arguments: <container-id> (required) · <arguments> (new process args, passthrough — first arg is the executable).

Flag	Value	Default	Description
-d, --detach	flag	false	Run the process and detach from it.

Plus the full Process options group (-e/--env, --env-file, --gid, -i/--interactive, -t/--tty, -u/--user, --uid, -w/--workdir/--cwd, --ulimit) — exec composes the same Flags.Process group as run/create, so all of these are accepted on exec too.

container exec -it web /bin/sh
container exec -e DEBUG=1 -u root web env

---

container start

Start a stopped container. Optionally attach to its output and keep stdin open.

container start [-a] [-i] <container-id>

Arguments: <container-id> (required).

Flag	Value	Default	Description
-a, --attach	flag	false	Attach stdout/stderr.
-i, --interactive	flag	false	Attach stdin.

If neither -a nor -i is given, the container runs detached.

container start web
container start -ai mybox

---

container stop

Gracefully stop running containers by sending a signal, then SIGKILL after a timeout.

container stop [-a] [-s <signal>] [-t <time>] [<container-ids> ...]

Arguments: <container-ids> (zero or more; nothing is stopped without IDs unless -a).

Flag	Value	Default	Description
-a, --all	flag	false	Stop all running containers.
-s, --signal	<signal>	SIGTERM (effective)	Signal to send. The CLI flag itself has no hard default — when omitted the server applies the graceful default (SIGTERM).
-t, --time	<seconds>	5	Seconds to wait before SIGKILL.

Aliases: none.

container stop web
container stop -a
container stop -s SIGINT -t 10 web db

---

container kill

Immediately signal (default KILL) running containers. No graceful shutdown — use with care.

container kill [-a] [-s <signal>] [<container-ids> ...]

Arguments: <container-ids> (zero or more; nothing killed without IDs unless -a).

Flag	Value	Default	Description
-a, --all	flag	false	Kill/signal all running containers.
-s, --signal	<signal>	KILL	Signal to send.

container kill web
container kill -s HUP -a

---

container delete (rm)

Delete one or more containers. Running containers require --force.

container delete [-a] [-f] [<container-ids> ...]
container rm     [-a] [-f] [<container-ids> ...]

Aliases: rm. Arguments: <container-ids> (zero or more; nothing deleted without IDs unless -a).

Flag	Value	Default	Description
-a, --all	flag	false	Delete all containers.
-f, --force	flag	false	Delete even if running.

container delete web
container rm -f web
container rm --all

---

container list (ls)

List containers. By default only running ones are shown.

container list [-a] [--format <format>] [-q]
container ls   [-a] [--format <format>] [-q]

Aliases: ls.

Flag	Value	Default	Description
-a, --all	flag	false	Include non-running containers.
--format	json|table|yaml|toml	table	Output format.
-q, --quiet	flag	false	Only output the container ID.

container ls
container ls -a --format json
container ls -q

---

container logs

Fetch a container's logs. Follow, tail, or view the boot log.

container logs [--boot] [-f] [-n <n>] <container-id>

Arguments: <container-id> (required).

Flag	Value	Default	Description
--boot	flag	false	Show the boot log instead of stdio.
-f, --follow	flag	false	Follow log output.
-n	<n>	— (all)	Show the last n lines. -n is short-only (no --lines). Omit to print everything.

container logs -f web
container logs -n 100 web
container logs --boot web

---

container inspect

Print detailed container info as pretty JSON.

container inspect <container-ids> ...

Arguments: <container-ids> (one or more, required). Duplicates de-duplicated; a missing ID errors.

No options beyond global.

container inspect web
container inspect web db

---

container stats

Real-time resource usage (CPU %, memory, net I/O, block I/O, PIDs). Interactive by default (like top); --no-stream gives one snapshot.

container stats [--format <format>] [--no-stream] [<container-ids> ...]

Arguments: <container-ids> (optional; all running containers if omitted).

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format. Any non-table format implies a single snapshot.
--no-stream	flag	false	Single snapshot instead of streaming.

container stats
container stats web db cache
container stats --no-stream web
container stats --format json --no-stream web

---

container copy (cp)

⚠️ Requires 1.0.0+ (added after 0.7.1).

Copy files between a running container and the host. Exactly one side must be a container reference container_id:path.

container copy <source> <destination>
container cp   <source> <destination>

Aliases: cp. Arguments: <source>, <destination> (each a local path or container_id:path).

No options beyond global.

container cp ./config.json web:/etc/app/
container cp web:/var/log/app.log ./logs/

---

container export

⚠️ Requires 1.0.0+ (added after 0.7.1). The container must be stopped first, or it errors invalidState: "container is not stopped".

Export a stopped container's filesystem as a tar archive. Streams to stdout if -o omitted.

container export [-o <output>] <container-id>

Arguments: <container-id> (required).

Flag	Value	Default	Description
-o, --output	<path>	stdout	Pathname for the saved filesystem tar.

container stop mybox
container export -o mybox.tar mybox
container export mybox > mybox.tar

---

container prune

⚠️ Requires 1.0.0+ (added after 0.7.1). Removes all stopped containers — distinct from container image prune / container volume prune.

Remove stopped containers to reclaim disk space; prints the space freed.

container prune

No arguments, no options beyond global.

---

Images

container build

Build an OCI image from a local context using BuildKit (in an isolated builder container). When -f is not given, looks for Dockerfile, then falls back to Containerfile.

container build [<options>] [<context-dir>]

Arguments: <context-dir> (default .).

Flag	Value	Default	Description
-a, --arch	<value>	host arch (e.g. arm64)	Add an architecture to the build (comma-separated and/or repeatable).
--build-arg	<key=val>	—	Build-time variable. Repeatable.
--cache-in	<value>	—	(Hidden/advanced) BuildKit cache import. Repeatable.
--cache-out	<value>	—	(Hidden/advanced) BuildKit cache export. Repeatable.
-c, --cpus	<n>	2	CPUs for the builder container.
--dns	<ip>	—	DNS nameserver IP for the build. Repeatable.
--dns-domain	<domain>	—	Default DNS domain.
--dns-option	<option>	—	DNS option. Repeatable.
--dns-search	<domain>	—	DNS search domain. Repeatable.
-f, --file	<path>	Dockerfile→Containerfile	Path to the Dockerfile/Containerfile.
-l, --label	<key=val>	—	Set a label. Repeatable.
-m, --memory	<size>	2048MB	Builder container memory; optional K/M/G/T/P suffix.
--no-cache	flag	false	Do not use the build cache.
-o, --output	<value>	type=oci	Output config (type=<oci|tar|local>[,dest=]).
--os	<value>	linux	Add an OS to the build (comma-separated and/or repeatable).
--platform	<platform>	—	Add a platform (os/arch[/variant]); precedence over --os/--arch. [env: CONTAINER_DEFAULT_PLATFORM]
--progress	auto|plain|tty	auto	Build progress type. (Note the values differ from the pull/push progress set.)
--pull	flag	false	Pull the latest base image.
-q, --quiet	flag	false	Suppress build output.
--secret	id=<key>,...	—	Build secret (id=<key>[,env=<ENV_VAR>|,src=<local/path>]). Repeatable.
-t, --tag	<name>	—	Name/tag for the built image. Repeatable.
--target	<stage>	""	Target build stage.
--vsock-port	<port>	8088	Builder shim vsock port.

container build -t my-app:latest .
container build -f docker/Dockerfile.prod -t my-app:prod .
container build --build-arg NODE_VERSION=18 -t my-app .
container build --target production --no-cache -t my-app:prod .
container build -t my-app:latest -t my-app:v1.0.0 .

---

container image group

Manage images. Alias: i. (The plural images is only the help section header, not a command — container images errors with "plugin not found".)

container image <subcommand>
container i     <subcommand>

Subcommands: pull, push, tag, save, load, inspect, list/ls, delete/rm, prune.

---

container image pull

Pull an image from a registry.

container image pull [--scheme <scheme>] [--progress <type>] [--max-concurrent-downloads <n>] [-a <arch>] [--os <os>] [--platform <platform>] <reference>

Arguments: <reference> (required).

Flag	Value	Default	Description
-a, --arch	<arch>	—	Limit to the specified architecture.
--os	<os>	—	Limit to the specified OS.
--platform	<platform>	—	Limit to platform (os/arch[/variant]); precedence over --os/--arch. [env: CONTAINER_DEFAULT_PLATFORM]
--scheme	http|https|auto	auto	Registry connection scheme.
--progress	auto|none|ansi|plain|color	auto	Progress type.
--max-concurrent-downloads	<n>	3	Max concurrent blob downloads.

container image pull docker.io/library/alpine:latest
container image pull --platform linux/arm64 ubuntu:24.04
container image pull --scheme http --max-concurrent-downloads 6 registry.local:5000/myapp:dev

---

container image push

Push an image to a registry. Same as pull minus --max-concurrent-downloads.

container image push [--scheme <scheme>] [--progress <type>] [-a <arch>] [--os <os>] [--platform <platform>] <reference>

Arguments: <reference> (required).

Flag	Value	Default	Description
-a, --arch	<arch>	—	Limit to architecture.
--os	<os>	—	Limit to OS.
--platform	<platform>	—	Limit to platform; precedence over --os/--arch. [env: CONTAINER_DEFAULT_PLATFORM]
--scheme	http|https|auto	auto	Registry connection scheme.
--progress	auto|none|ansi|plain|color	auto	Progress type.

On success the final image reference is printed to stdout.

container image push registry.local:5000/myapp:1.0.0
container image push --platform linux/amd64 docker.io/me/tool:latest

---

container image tag

Add a new reference to an existing image. Original reference is unchanged.

container image tag <source> <target>

Arguments: <source> (image-name[:tag]), <target> (new reference). No options beyond global. On success the normalized target is printed.

container image tag alpine:latest myregistry.local/alpine:pinned
container image tag ubuntu:24.04 ubuntu:lts

---

container image save

Save one or more images as an OCI-compatible tar archive. Streams to stdout if -o omitted.

container image save [-a <arch>] [--os <os>] [-o <output>] [--platform <platform>] <references> ...

Arguments: <references> (one or more, required).

Flag	Value	Default	Description
-a, --arch	<arch>	—	Architecture for the saved image.
--os	<os>	—	OS for the saved image.
-o, --output	<path>	stdout	Pathname for the saved tar (resolved to absolute).
--platform	<platform>	—	Platform (os/arch[/variant]); precedence over --os/--arch. [env: CONTAINER_DEFAULT_PLATFORM]

Every reference must resolve; if a platform is resolved, each image must contain content for it (else it errors listing available platforms). Without -o, the tar goes to stdout and the saved reference list is written to stderr (so it doesn't corrupt the stream).

container image save -o images.tar alpine:latest ubuntu:24.04
container image save --platform linux/arm64 -o app-arm64.tar myapp:1.0
container image save alpine:latest > alpine.tar

---

container image load

Load images from an OCI tar archive. Reads stdin if -i omitted.

container image load [-i <input>] [-f]

No positional arguments.

Flag	Value	Default	Description
-i, --input	<path>	stdin	Path to the tar archive (resolved to absolute).
-f, --force	flag	false	Load even if the archive contains invalid member files.

If --input names a missing file, the command logs an error and exits 1. Loaded references are printed to stdout; rejected members are warned.

container image load -i images.tar
container image load --force --input suspect-archive.tar
cat alpine.tar | container image load

---

container image inspect

Print detailed image info as pretty JSON.

container image inspect <images> ...

Arguments: <images> (one or more, required). Duplicates de-duplicated; a missing image errors. Infra images (builder / vminit) are filtered out. No options beyond global.

container image inspect alpine:latest
container image inspect alpine:latest ubuntu:24.04

---

container image list (ls)

List local images. Alias: ls.

container image list [--format <format>] [-q] [-v]
container image ls   [--format <format>] [-q] [-v]

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format.
-q, --quiet	flag	false	Only output the image name.
-v, --verbose	flag	false	Verbose (one row per platform variant).

-q and -v are mutually exclusive (error if both). Infra images are always hidden; results sorted by reference. Verbose columns: NAME, TAG, INDEX DIGEST, OS, ARCH, VARIANT, FULL SIZE, CREATED, MANIFEST DIGEST.

container image list
container image ls --format json
container image ls -q
container image list --verbose

---

container image delete (rm)

Delete one or more images. Alias: rm.

container image delete [-a] [-f] [<images> ...]
container image rm     [-a] [-f] [<images> ...]

Arguments: <images> (zero or more).

Flag	Value	Default	Description
-a, --all	flag	false	Delete all images.
-f, --force	flag	false	Ignore "not found" errors.

Exactly one of explicit images or --all must be supplied (supplying both, or neither, errors). Infra images skipped; orphaned blobs are GC'd afterward and reclaimed space is logged.

container image delete alpine:latest
container image rm --all
container image delete --force ghost:missing alpine:latest

---

container image prune

⚠️ Requires 1.0.0+ (added after 0.7.1).

Remove unused images to reclaim space. Default removes only dangling (untagged) images; -a removes every image not referenced by any container.

container image prune [-a]

Flag	Value	Default	Description
-a, --all	flag	false	Remove all unused images, not just dangling ones.

container image prune
container image prune --all

---

Registry

Manage registry logins. Group alias: r. Nested under the Image group. Credentials are stored in the macOS keychain.

Note: source declares only login, logout, and list. There is no registry default get/set command in the current source (despite occasional mentions of "default registry" elsewhere — that concept lives in system configuration, not this group).

container registry <subcommand>
container r         <subcommand>

---

container registry login

Authenticate with a registry; credentials are saved to the keychain for reuse.

container registry login [--scheme <scheme>] [--password-stdin] [-u <username>] <server>

Arguments: <server> (registry server name, required).

Flag	Value	Default	Description
--scheme	http|https|auto	auto	Registry connection scheme.
--password-stdin	flag	false	Read the password from stdin. Requires --username.
-u, --username	<username>	""	Registry username.

Behavior: --password-stdin without --username errors ("must provide --username with --password-stdin"). With no username supplied, prompts interactively for username; with no password, prompts interactively. On success it pings the registry (retrying on 5xx) and stores the credentials, logging "Login succeeded".

container registry login registry.example.com                 # prompts for user + password
container registry login -u alice ghcr.io                      # prompts for password only
echo "$TOKEN" | container registry login -u alice --password-stdin ghcr.io
container registry login --scheme http localhost:5000

---

container registry logout

Log out, removing stored credentials for the registry.

container registry logout <registry>

Arguments: <registry> (required). No options beyond global.

container registry logout ghcr.io
container r logout registry.example.com

---

container registry list (ls)

⚠️ Requires 1.0.0+ (added after 0.7.1). On 0.7.1 the registry group had only login/logout.

List saved registry logins. Alias: ls.

container registry list [--format <format>] [-q]
container r ls          [--format <format>] [-q]

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format.
-q, --quiet	flag	false	Only output the registry hostname.

Table columns: HOSTNAME, USERNAME, MODIFIED, CREATED (ISO-8601 dates).

container registry list
container registry list --format json
container registry ls -q

---

Builder

Manage the BuildKit-based builder container used by container build. No group alias.

container builder <subcommand>

Subcommands: start, status, stop, delete/rm.

---

container builder start

Start the BuildKit builder container.

container builder start [-c <cpus>] [-m <memory>] [--dns <ip> ...] [--dns-domain <domain>] [--dns-option <option> ...] [--dns-search <domain> ...]

Flag	Value	Default	Description
-c, --cpus	<n>	2	CPUs for the builder container.
-m, --memory	<size>	2048MB	Builder memory; optional K/M/G/T/P suffix.
--dns	<ip>	—	DNS nameserver IP. Repeatable.
--dns-domain	<domain>	—	Default DNS domain.
--dns-option	<option>	—	DNS option. Repeatable.
--dns-search	<domain>	—	DNS search domain. Repeatable.

container builder start
container builder start -c 4 -m 4G

---

container builder status

Show the builder's status.

container builder status [--format <format>] [-q]

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format.
-q, --quiet	flag	false	Only output the container ID.

When the builder is not running, table output prints builder is not running (or empty with -q).

---

container builder stop

Stop the builder container.

container builder stop

No arguments, no options beyond global.

---

container builder delete (rm)

Delete the builder container. Alias: rm.

container builder delete [-f]
container builder rm     [-f]

Flag	Value	Default	Description
-f, --force	flag	false	Delete even if the builder is running (else it errors: "BuildKit container is not stopped, use --force to override").

---

System

Manage the container background services (apiserver + helpers), logs, disk usage, DNS domains, the default kernel, and system properties. Group alias: s. macOS hosts only.

container system <subcommand>
container s       <subcommand>

Subcommands: start, stop, status, version, logs, df, dns (group), kernel (group), property (group).

A deeper guide to the config.toml/property schema, DNS, default-kernel selection, and data locations lives in references/configuration.md. This section documents the CLI surface.

---

container system start

Start the container services (and optionally install a default kernel). Starts container-apiserver and background services.

container system start [-a <app-root>] [--install-root <path>] [--log-root <path>] [--enable-kernel-install | --disable-kernel-install] [--timeout <seconds>]

Flag	Value	Default	Description
-a, --app-root	<path>	app-data default	Root directory for application data.
--install-root	<path>	install default	Root directory for executables and plugins.
--log-root	<path>	(macOS log facility)	Root directory for log data. When set, services write only to files here (and container system logs shows nothing). Intended for short-term diagnostics: no aggregation, no rotation.
--enable-kernel-install / --disable-kernel-install	flag pair	prompt user	Whether to install the default kernel. Omit to be prompted interactively.
--timeout	<seconds>	system default	Seconds to wait for the API service to become responsive.

container system start
container system start --enable-kernel-install

---

container system stop

Stop the services and deregister them from launchd.

container system stop [-p <prefix>]

Flag	Value	Default	Description
-p, --prefix	<prefix>	com.apple.container.	Launchd prefix for the services to stop.

---

container system status

Check whether the services are running (sends a health check to the API server).

container system status [-p <prefix>] [--format <format>]

Flag	Value	Default	Description
-p, --prefix	<prefix>	com.apple.container.	Launchd prefix for the services.
--format	json|table|yaml|toml	table	Output format.

---

container system version

⚠️ Requires 1.0.0+ (added after 0.7.1). The top-level container --version flag exists in all versions; only the system version subcommand is newer.

Show CLI and (if reachable) API-server version info.

container system version [--format <format>]

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format.

Table columns: COMPONENT, VERSION, BUILD, COMMIT. A second row for container-apiserver appears when the server answers the health check.

---

container system logs

Show logs from the container services.

container system logs [-f] [--last <period>]

Flag	Value	Default	Description
-f, --follow	flag	false	Follow log output.
--last	<period>	5m	Fetch logs from the given period ago. Format <number>[m|h|d] (bare number = seconds).

If services were started with --log-root, they log only to files and this command shows nothing.

container system logs -f
container system logs --last 1h

---

container system df

Show disk usage for images, containers, and volumes (total count, active count, size, reclaimable).

container system df [--format <format>]

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format.

---

container system dns

Manage local DNS domains for containers. Requires administrator privileges (sudo) for create/delete.

container system dns <create|delete|list>

container system dns create

sudo container system dns create [--localhost <ip>] <domain-name>

Arguments: <domain-name> (required).

Flag	Value	Default	Description
--localhost	<ip>	—	IPv4 address to redirect to localhost.

container system dns delete (rm)

sudo container system dns delete <domain-name>
sudo container system dns rm     <domain-name>

Alias: rm. Arguments: <domain-name> (required). No options beyond global.

container system dns list (ls)

container system dns list [--format <format>] [-q]
container system dns ls   [--format <format>] [-q]

Alias: ls.

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format.
-q, --quiet	flag	false	Only output the domain.

---

container system kernel set

Install or update the Linux kernel used by the container runtime.

container system kernel set [--arch <arch>] [--binary <path>] [--force] [--recommended] [--tar <tar>]

Flag	Value	Default	Description
--arch	amd64|arm64	arm64	Architecture of the kernel binary.
--binary	<path>	—	Path to the kernel file (or archive member if used with --tar).
--force	flag	false	Overwrite an existing kernel of the same name.
--recommended	flag	false	Download and install the recommended default kernel (takes precedence over all other flags).
--tar	<tar>	—	Filesystem path or remote URL to a tar archive containing a kernel file.

container system kernel set --recommended
container system kernel set --binary ./vmlinux --arch arm64 --force
container system kernel set --tar https://example.com/kernel.tar --binary boot/vmlinux

---

container system property list (ls)

List system properties with current values. Alias: ls.

container system property list [--format <format>]
container system property ls   [--format <format>]

Flag	Value	Default	Description
--format	json|toml	toml	Output format. Note: only json/toml here (not the full ListFormat set).

container system property list
container system property list --format json

---

Network (macOS 26+)

Availability: the entire container network group requires macOS 26 or later. On macOS 15 the command group is absent and only a single default subnet is available.

Manage user-defined container networks. Group alias: n.

container network <subcommand>
container n        <subcommand>

Subcommands: create, delete/rm, list/ls, inspect, prune.

---

container network create

Create a network.

container network create [--internal] [--label <label> ...] [--option <option> ...] [--plugin <plugin>] [--subnet <subnet>] [--subnet-v6 <subnet-v6>] <name>

Arguments: <name> (required).

Flag	Value	Default	Description
--internal	flag	false	Restrict to a host-only network (NAT otherwise).
--label	<key=value>	—	Network metadata. Repeatable.
--option	<key=value>	—	Plugin-specific option. Repeatable.
--plugin	<plugin>	container-network-vmnet	Network plugin to use.
--subnet	<cidr>	—	IPv4 subnet (e.g. 192.168.100.0/24).
--subnet-v6	<cidr>	—	IPv6 prefix (e.g. fd00:1234::/64).

container network create mynet
container network create --subnet 192.168.100.0/24 mynet
container network create --internal isolated

---

container network delete (rm)

Delete one or more networks. Alias: rm.

container network delete [-a] [<network-names> ...]
container network rm     [-a] [<network-names> ...]

Arguments: <network-names> (zero or more; nothing deleted without names unless -a).

Flag	Value	Default	Description
-a, --all	flag	false	Delete all networks.

container network delete mynet
container network rm net1 net2
container network delete --all

---

container network list (ls)

List user-defined networks. Alias: ls.

container network list [--format <format>] [-q]
container network ls   [--format <format>] [-q]

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format.
-q, --quiet	flag	false	Only output the network name.

---

container network inspect

Print detailed info for one or more networks.

container network inspect <networks> ...

Arguments: <networks> (one or more, required). No options beyond global.

---

container network prune

Remove networks not connected to any containers. Default and system networks are preserved.

container network prune

No arguments, no options beyond global.

---

Volume

Manage persistent volumes. Group alias: v. Volumes may be created explicitly or implicitly (-v myvol:/path, or -v /path for an anonymous volume).

container volume <subcommand>
container v       <subcommand>

Subcommands: create, delete/rm, list/ls, inspect, prune.

---

container volume create

Create a named volume.

container volume create [--label <label> ...] [--opt <opt> ...] [-s <size>] <name>

Arguments: <name> (required).

Flag	Value	Default	Description
--label	<key=value>	—	Volume metadata. Repeatable.
--opt	<key=value>	—	Driver-specific option. Repeatable.
-s	<size>	—	Volume size in bytes; optional K/M/G/T/P suffix. Takes precedence over --opt size=.

Driver options (--opt key=value, default local driver):

• size=<value> — volume size (unit suffixes as above; min 1 MiB). Equivalent to -s; -s wins if both set.
• journal=<mode>[:<size>] — ext4 journaling. <mode> ∈ ordered (metadata only, data-before-metadata; kernel default), writeback (metadata only, no data ordering; fastest, least safe), journal (metadata + data; safest). Optional :<size> sets the journal size.

container volume create --opt journal=ordered myvol
container volume create --opt journal=writeback:64m myvol
container volume create --opt journal=journal --opt size=10g myvol
container volume create -s 5G data

Anonymous volumes: auto-created with -v /path or --mount type=volume,dst=/path (UUID name anon-…). Unlike Docker, they do not auto-clean with --rm — delete manually.

container run -v /data alpine
VOL=$(container volume list -q | grep anon); container volume rm "$VOL"

---

container volume delete (rm)

Delete one or more volumes. Volumes in use (by running or stopped containers) cannot be deleted. Alias: rm.

container volume delete [-a] [<names> ...]
container volume rm     [-a] [<names> ...]

Arguments: <names> (zero or more; nothing deleted without names unless -a).

Flag	Value	Default	Description
-a, --all	flag	false	Delete all volumes.

container volume delete myvol
container volume delete vol1 vol2 vol3
container volume delete --all

---

container volume list (ls)

List volumes. Alias: ls.

container volume list [--format <format>] [-q]
container volume ls   [--format <format>] [-q]

Flag	Value	Default	Description
--format	json|table|yaml|toml	table	Output format.
-q, --quiet	flag	false	Only output the volume name.

---

container volume inspect

Print detailed info for one or more volumes as JSON.

container volume inspect <names> ...

Arguments: <names> (one or more, required). No options beyond global.

---

container volume prune

Remove all volumes with no container references; reports disk space reclaimed.

container volume prune

No arguments, no options beyond global.

---

Machine

⚠️ Requires 1.0.0+ — the entire container machine group was added after 0.7.1. Verify with container machine --help on your install.

Manage container machines (the Linux VMs that host containers). Group alias: m. Commands that take an optional machine ID use the default machine when omitted. Changes to a running machine's config take effect after stop + restart.

container machine <subcommand>
container m        <subcommand>

Subcommands: create, run, set, set-default, list/ls, inspect, logs, stop, delete/rm.

---

container machine create

Create a container machine from an image and boot it (unless --no-boot).

container machine create [<options>] <image>

Arguments: <image> (e.g. alpine:3.22, required).

Flag	Value	Default	Description
-n, --name	<name>	—	Name for the machine.
--set-default	flag	false	Set this machine as the default.
--no-boot	flag	false	Create without booting.
--cpus	<n>	—	Number of virtual CPUs.
--memory	<size>	half of system memory	Memory allocation (e.g. 2G, 8G).
--home-mount	ro|rw|none	rw	How to mount the user's home directory.
--virtualization	flag	false	Enable nested virtualization. Requires Apple silicon M3+, macOS 15+, and a kernel with CONFIG_KVM=y.
--kernel	<path>	—	Path to a custom kernel binary (e.g. vmlinux).
-a, --arch	<arch>	host arch	Arch for a multi-arch image.
--os	<os>	linux	OS for a multi-OS image.
--platform	<platform>	—	Platform for a multi-platform image; precedence over --os/--arch.
--scheme	http|https|auto	auto	Registry connection scheme.
--progress	auto|none|ansi|plain|color	auto	Progress type.
--max-concurrent-downloads	<n>	3	Max concurrent blob downloads.

container machine create alpine:3.22 --name my-machine
container machine create --cpus 4 --memory 8G --set-default alpine:3.22
container machine create --no-boot alpine:3.22
container machine create --virtualization --kernel ./vmlinux-kvm alpine:3.22

---

container machine run

Run a command in a machine (booting it first if needed). With no command, opens an interactive login shell. Runs as a user matching the host user unless --root.

container machine run [<options>] [<executable>] [<arguments> ...]

Arguments: <executable> (default: login shell) · <arguments> (passthrough).

Flag	Value	Default	Description
-n, --name	<name>	default machine	Machine ID.
-d, --detach	flag	false	Run detached.
--root	flag	false	Run as root instead of matching the host user.

Plus the Process options group (-e/--env, --env-file, --gid, -i/--interactive, -t/--tty, -u/--user, --uid, -w/--workdir/--cwd).

container machine run
container machine run -n my-machine uname -a
container machine run -n my-machine -- cat /proc/cpuinfo

---

container machine set

Set config values on a machine (applied after stop + restart).

container machine set [-n <name>] <setting> ...

Arguments: <setting> (one or more key=value).

Flag	Value	Default	Description
-n, --name	<name>	default machine	Machine ID.

Settings: cpus=<n> · memory=<size> (e.g. 2G; default half of system memory) · home-mount=<ro\|rw\|none> (default rw) · virtualization=<true\|false> (M3+, macOS 15+, CONFIG_KVM=y) · kernel=<path> (empty kernel= clears the override → system default).

container machine set cpus=4 memory=8G
container machine set -n my-machine home-mount=ro
container machine set virtualization=true kernel=/opt/kernels/vmlinux-kvm
container machine set kernel=          # clear custom kernel

---

container machine set-default

Set the default machine.

container machine set-default <id>

Arguments: <id> (required). No options beyond global.

---

container machine list (ls)

List machines; the default is marked in the DEFAULT column. Alias: ls.

container machine list [--format <format>] [-q]
container machine ls   [--format <format>] [-q]

Flag	Value	Default	Description
--format	json|table	table	Output format. Note: machines support only json/table (not yaml/toml).
-q, --quiet	flag	false	Only output the machine ID.

---

container machine inspect

Print detailed machine info as JSON. Uses the default machine if no ID given.

container machine inspect [<id>]

Arguments: <id> (optional; default machine if omitted). No options beyond global.

---

container machine logs

Fetch a machine's logs. Follow, tail, or view the boot log. Default machine if no ID given.

container machine logs [--boot] [-f] [-n <n>] [<id>]

Arguments: <id> (optional; default machine if omitted).

Flag	Value	Default	Description
--boot	flag	false	Show the boot log instead of stdio.
-f, --follow	flag	false	Follow log output.
-n	<n>	— (all)	Show the last n lines. -n is short-only.

---

container machine stop

Stop a running machine. Default machine if no ID given.

container machine stop [<id>]

Arguments: <id> (optional; default machine if omitted). No options beyond global.

---

container machine delete (rm)

Delete a machine, stopping it first if running. If it was the default, set a new one with container machine set-default. Alias: rm.

container machine delete <id>
container machine rm     <id>

Arguments: <id> (required). No options beyond global.