How to Use the Command Reference in apple/container: A Complete Guide

The command reference in apple/container is a comprehensive markdown documentation file located at 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.

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 in the repository root. This file is generated from and kept in sync with 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.

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 <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 <dir> – Set the initial working directory inside the container

These definitions are extracted directly from the Swift ArgumentParser implementations in Sources/CLI/ContainerCLI.swift.

Running Example Commands

Each command section concludes with practical examples. Replace placeholder values (denoted by <image> or <container-id>) 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

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

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

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

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

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

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

container export -o mycontainer.tar mycontainer

Exports the container's root filesystem to a tarball named mycontainer.tar.

Scripting with JSON Output

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 defines the command hierarchy using Swift's ArgumentParser library (defined in Package.swift). The markdown file at 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 and append the corresponding section to command-reference.md.

Summary

• The definitive command reference for apple/container is located at docs/command-reference.md
• The reference is generated from 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 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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}