# How to Use the Command Reference in apple/container: A Complete Guide > Master the apple/container command reference. This guide details every CLI command, flag, and example, synced with Swift source code. Boost your workflow today. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-06 --- **The command reference in apple/container is a comprehensive markdown documentation file located at [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) that catalogs every Container CLI command, flag, and usage example, automatically synchronized with the Swift source code in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift).** The apple/container repository provides a native container management solution for macOS, and learning how to use the command reference is essential for mastering the Container CLI. The reference documentation serves as the definitive source for command syntax, argument validation, and practical examples, generated directly from the CLI implementation to ensure accuracy. ## Where to Find the Command Reference The primary command reference file is located at **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** in the repository root. This file is generated from and kept in sync with **[`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift)**, which implements the top-level `container` command and registers all sub-commands including `run`, `build`, `image`, `network`, `volume`, `system`, and `machine`. The reference is branch-specific and always reflects the current state of the code. For stable release documentation, switch to the corresponding Git tag (e.g., `0.4.1`) and view the file under that specific version. ## Structure of the Command Reference The command reference is organized into functional sections that mirror the architecture of [`ContainerCLI.swift`](https://github.com/apple/container/blob/main/ContainerCLI.swift). ### Command Hierarchy The reference follows the CLI structure: - **Core Commands**: `container run`, `container build`, `container list` - **Image Management**: `container image list`, `container image pull`, `container image rm` - **Network Management**: `container network create`, `container network ls` - **Volume Management**: `container volume create`, `container volume rm` - **System Commands**: `container system version`, `container system info` ### Documentation Components Each command entry includes four essential components: - **Usage Block**: The exact command syntax with positional arguments and flags - **Arguments Table**: Required parameters and their expected formats - **Options Table**: Short/long flags (e.g., `-i, --interactive`), descriptions, and value requirements - **Examples Section**: Copy-paste ready commands demonstrating typical workflows ## How to Navigate and Use the Reference ### Locating Specific Commands Use your browser's search function (`Ctrl+F` or `Cmd+F`) to find keywords like `run`, `volume`, or `registry`. The file follows a logical hierarchy where each H2 section represents a functional area, and each H3 subsection documents a specific sub-command. ### Understanding Option Tables Every option is documented with its short flag, long flag, and value format. For example, the `container run` documentation lists: - `-e, --env ` – Set environment variables using `key=value` or just `key` - `-i, --interactive` – Keep STDIN open for interactive sessions - `-t, --tty` – Allocate a pseudo-TTY for terminal interaction - `-w, --workdir, --cwd ` – Set the initial working directory inside the container These definitions are extracted directly from the Swift `ArgumentParser` implementations in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift). ### Running Example Commands Each command section concludes with practical examples. Replace placeholder values (denoted by `` or ``) with your specific values before execution. ## Practical Examples from the Command Reference The following examples demonstrate how to use the command reference for common container operations on macOS. ### Starting an Interactive Shell ```bash container run -it ubuntu:latest /bin/bash ``` This allocates a TTY (`-t`), keeps STDIN open (`-i`), and launches a bash shell in the Ubuntu image. ### Running a Detached Container with Port Mapping ```bash container run -d --name web -p 8080:80 nginx:latest ``` The `-d` flag runs the container in detached mode, `--name` assigns a specific identifier, and `-p` publishes port 80 to the host's port 8080. ### Setting Environment Variables and Resource Limits ```bash container run -e NODE_ENV=production --cpus 2 --memory 1G node:18 ``` This passes the `NODE_ENV` environment variable and restricts the container to 2 CPUs and 1GB of RAM. ### Creating a User-Defined Network ```bash container network create --subnet 192.168.100.0/24 mynet ``` Creates a bridge network named `mynet` with the specified subnet. Note that network commands require macOS 26+ as indicated in the reference. ### Mounting Host Directories ```bash container run -v /host/data:/container/data alpine:latest ``` Binds the host directory `/host/data` to `/container/data` inside the container using a volume mount. ### Building with a Custom Dockerfile ```bash container build -f Dockerfile.prod -t my-app:prod . ``` Uses `Dockerfile.prod` instead of the default `Dockerfile` and tags the resulting image as `my-app:prod`. ### Exporting Container Filesystems ```bash container export -o mycontainer.tar mycontainer ``` Exports the container's root filesystem to a tarball named `mycontainer.tar`. ### Scripting with JSON Output ```bash container image list --format json container list --format json ``` Most list commands accept `--format` with options including `json`, `yaml`, `toml`, or `table` for automation pipelines. ## How the Reference Stays Synchronized with Code The command reference is not manually maintained separately from the code. According to the apple/container source code, [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift) defines the command hierarchy using Swift's `ArgumentParser` library (defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift)). The markdown file at [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) is generated or validated against these definitions, ensuring that every flag, option, and sub-command documented actually exists in the implementation. The repository's CI pipeline checks that the reference remains in sync with the CLI implementation. When contributing new commands, developers must update both [`ContainerCLI.swift`](https://github.com/apple/container/blob/main/ContainerCLI.swift) and append the corresponding section to [`command-reference.md`](https://github.com/apple/container/blob/main/command-reference.md). ## Summary - The definitive command reference for apple/container is located at **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** - The reference is generated from **[`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift)** and kept synchronized via CI checks - Each command entry includes Usage syntax, Arguments/Options tables, and practical Examples - Use **`--format json`** (or `yaml`, `toml`) for machine-readable output suitable for scripting - Check version-specific notes within the reference, as some features like network management require macOS 26+ - The CLI communicates with the container-apiserver via a local UNIX socket, delegating all container operations ## Frequently Asked Questions ### Where is the command reference file located in the apple/container repository? The command reference is located at **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** in the repository root. This file contains the complete documentation for the Container CLI, including all sub-commands, flags, and usage examples derived from the source code in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift). ### How do I find specific command examples in the reference? Use your browser's find function (`Ctrl+F`) to search for the command name or keyword. The reference is organized into sections like "Core Commands" and "Image Management," with each command documented under its functional area. Every command section includes an **Examples** subsection with copy-paste ready commands. ### What output formats does the Container CLI support for list commands? The Container CLI supports **`json`**, **`yaml`**, **`toml`**, and **`table`** output formats. Append `--format json` (or your preferred format) to list commands like `container image list` or `container list` to receive machine-readable output suitable for automation scripts and pipelines. ### How is the command reference kept up to date with the code implementation? The reference is maintained in sync with the Swift implementation through repository CI checks. Since [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift) defines the command structure using `ArgumentParser`, and the reference documents these definitions, the CI pipeline validates that both files remain consistent. When developers add new sub-commands or flags, they must update both the source code and the markdown documentation.