opencode-skills-collection 3.1.23 → 4.0.1

package/bundled-skills/apple-container/references/commands.md

@@ -0,0 +1,1593 @@
+# `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](#global)
+- [Container lifecycle](#container-lifecycle)
+  - [run](#container-run) · [create](#container-create) · [exec](#container-exec) · [start](#container-start) · [stop](#container-stop) · [kill](#container-kill) · [delete / rm](#container-delete-rm) · [list / ls](#container-list-ls) · [logs](#container-logs) · [inspect](#container-inspect) · [stats](#container-stats) · [copy / cp](#container-copy-cp) · [export](#container-export) · [prune](#container-prune)
+- [Images](#images)
+  - [build](#container-build) · [image](#container-image-group) · [pull](#container-image-pull) · [push](#container-image-push) · [tag](#container-image-tag) · [save](#container-image-save) · [load](#container-image-load) · [inspect](#container-image-inspect) · [list / ls](#container-image-list-ls) · [delete / rm](#container-image-delete-rm) · [prune](#container-image-prune)
+- [Registry](#registry)
+  - [login](#container-registry-login) · [logout](#container-registry-logout) · [list / ls](#container-registry-list-ls)
+- [Builder](#builder)
+  - [start](#container-builder-start) · [status](#container-builder-status) · [stop](#container-builder-stop) · [delete / rm](#container-builder-delete-rm)
+- [System](#system)
+  - [start](#container-system-start) · [stop](#container-system-stop) · [status](#container-system-status) · [version](#container-system-version) · [logs](#container-system-logs) · [df](#container-system-df) · [dns](#container-system-dns) · [kernel set](#container-system-kernel-set) · [property list](#container-system-property-list-ls)
+- [Network (macOS 26+)](#network-macos-26)
+  - [create](#container-network-create) · [delete / rm](#container-network-delete-rm) · [list / ls](#container-network-list-ls) · [inspect](#container-network-inspect) · [prune](#container-network-prune)
+- [Volume](#volume)
+  - [create](#container-volume-create) · [delete / rm](#container-volume-delete-rm) · [list / ls](#container-volume-list-ls) · [inspect](#container-volume-inspect) · [prune](#container-volume-prune)
+- [Machine](#machine)
+  - [create](#container-machine-create) · [run](#container-machine-run) · [set](#container-machine-set) · [set-default](#container-machine-set-default) · [list / ls](#container-machine-list-ls) · [inspect](#container-machine-inspect) · [logs](#container-machine-logs) · [stop](#container-machine-stop) · [delete / rm](#container-machine-delete-rm)
+
+---
+
+## Global
+
+Root command: `container` — "A container platform for macOS".
+
+```bash
+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
+`execvp`s 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-<arg>' 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.
+
+```bash
+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`.
+
+```bash
+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.
+
+```bash
+# 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.
+
+```bash
+container create [<options>] <image> [<arguments> ...]
+```
+
+**Arguments:** `<image>` (required) · `<arguments>` (init-process args, passthrough).
+
+**Options:** identical to [`container run`](#container-run).
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+container start web
+container start -ai mybox
+```
+
+---
+
+### `container stop`
+
+Gracefully stop running containers by sending a signal, then `SIGKILL` after a timeout.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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. |
+
+```bash
+container kill web
+container kill -s HUP -a
+```
+
+---
+
+### `container delete (rm)`
+
+Delete one or more containers. Running containers require `--force`.
+
+```bash
+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. |
+
+```bash
+container delete web
+container rm -f web
+container rm --all
+```
+
+---
+
+### `container list (ls)`
+
+List containers. By default only running ones are shown.
+
+```bash
+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. |
+
+```bash
+container ls
+container ls -a --format json
+container ls -q
+```
+
+---
+
+### `container logs`
+
+Fetch a container's logs. Follow, tail, or view the boot log.
+
+```bash
+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. |
+
+```bash
+container logs -f web
+container logs -n 100 web
+container logs --boot web
+```
+
+---
+
+### `container inspect`
+
+Print detailed container info as pretty JSON.
+
+```bash
+container inspect <container-ids> ...
+```
+
+**Arguments:** `<container-ids>` (one or more, required). Duplicates de-duplicated; a missing ID errors.
+
+No options beyond global.
+
+```bash
+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.
+
+```bash
+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. |
+
+```bash
+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`.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+container export [-o <output>] <container-id>
+```
+
+**Arguments:** `<container-id>` (required).
+
+| Flag | Value | Default | Description |
+|------|-------|---------|-------------|
+| `-o, --output` | `<path>` | stdout | Pathname for the saved filesystem tar. |
+
+```bash
+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.
+
+```bash
+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`.
+
+```bash
+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. |
+
+```bash
+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".)
+
+```bash
+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.
+
+```bash
+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. |
+
+```bash
+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`.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+container image tag <source> <target>
+```
+
+**Arguments:** `<source>` (`image-name[:tag]`), `<target>` (new reference). No options beyond global. On success the normalized target is printed.
+
+```bash
+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.
+
+```bash
+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).
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+container image inspect alpine:latest
+container image inspect alpine:latest ubuntu:24.04
+```
+
+---
+
+### `container image list (ls)`
+
+List local images. **Alias:** `ls`.
+
+```bash
+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`.
+
+```bash
+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`.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+container image prune [-a]
+```
+
+| Flag | Value | Default | Description |
+|------|-------|---------|-------------|
+| `-a, --all` | flag | `false` | Remove all unused images, not just dangling ones. |
+
+```bash
+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).
+
+```bash
+container registry <subcommand>
+container r         <subcommand>
+```
+
+---
+
+### `container registry login`
+
+Authenticate with a registry; credentials are saved to the keychain for reuse.
+
+```bash
+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"*.
+
+```bash
+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.
+
+```bash
+container registry logout <registry>
+```
+
+**Arguments:** `<registry>` (required). No options beyond global.
+
+```bash
+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`.
+
+```bash
+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).
+
+```bash
+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.**
+
+```bash
+container builder <subcommand>
+```
+
+Subcommands: `start`, `status`, `stop`, `delete`/`rm`.
+
+---
+
+### `container builder start`
+
+Start the BuildKit builder container.
+
+```bash
+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. |
+
+```bash
+container builder start
+container builder start -c 4 -m 4G
+```
+
+---
+
+### `container builder status`
+
+Show the builder's status.
+
+```bash
+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.
+
+```bash
+container builder stop
+```
+
+No arguments, no options beyond global.
+
+---
+
+### `container builder delete (rm)`
+
+Delete the builder container. **Alias:** `rm`.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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. |
+
+```bash
+container system start
+container system start --enable-kernel-install
+```
+
+---
+
+### `container system stop`
+
+Stop the services and deregister them from launchd.
+
+```bash
+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).
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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).
+
+```bash
+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`.
+
+```bash
+container system dns <create|delete|list>
+```
+
+#### `container system dns create`
+
+```bash
+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)`
+
+```bash
+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)`
+
+```bash
+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.
+
+```bash
+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. |
+
+```bash
+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`.
+
+```bash
+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). |
+
+```bash
+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`.
+
+```bash
+container network <subcommand>
+container n        <subcommand>
+```
+
+Subcommands: `create`, `delete`/`rm`, `list`/`ls`, `inspect`, `prune`.
+
+---
+
+### `container network create`
+
+Create a network.
+
+```bash
+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`). |
+
+```bash
+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`.
+
+```bash
+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. |
+
+```bash
+container network delete mynet
+container network rm net1 net2
+container network delete --all
+```
+
+---
+
+### `container network list (ls)`
+
+List user-defined networks. **Alias:** `ls`.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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).
+
+```bash
+container volume <subcommand>
+container v       <subcommand>
+```
+
+Subcommands: `create`, `delete`/`rm`, `list`/`ls`, `inspect`, `prune`.
+
+---
+
+### `container volume create`
+
+Create a named volume.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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`.
+
+```bash
+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. |
+
+```bash
+container volume delete myvol
+container volume delete vol1 vol2 vol3
+container volume delete --all
+```
+
+---
+
+### `container volume list (ls)`
+
+List volumes. **Alias:** `ls`.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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`).
+
+```bash
+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. |
+
+```bash
+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`.
+
+```bash
+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`).
+
+```bash
+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).
+
+```bash
+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).
+
+```bash
+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.
+
+```bash
+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`.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+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`.
+
+```bash
+container machine delete <id>
+container machine rm     <id>
+```
+
+**Arguments:** `<id>` (required). No options beyond global.