How to Understand the Apple/Container Command-Line Interface: Architecture and Usage

The Apple/container CLI is a Swift-based executable built on the ArgumentParser framework that defines sub-commands as AsyncParsableCommand structs in plugin helper files, parses flags through property wrappers like @Option and @Flag, and delegates runtime operations to service clients such as RuntimeClient.swift.

The apple/container repository provides a modern container management tool for macOS that exposes functionality through a comprehensive command-line interface. Understanding this CLI requires examining how Swift Package Manager assembles the binary, how individual commands declare their arguments and options, and how the tool communicates with underlying container runtimes.

CLI Architecture and Entry Points

The command-line interface follows a layered architecture that separates command definitions from execution logic.

Entry Point and Package Structure

The executable originates in Package.swift, which declares the container target and its dependency on the Swift ArgumentParser library. When built, the package generates a main.swift entry point that instantiates the root command structure and dispatches to sub-command implementations based on user input.

Command Definitions with AsyncParsableCommand

Each logical operation resides in separate files under Sources/Plugins/, such as RuntimeLinuxHelper.swift and NetworkVmnetHelper.swift. These files contain structs that conform to the AsyncParsableCommand protocol and declare a CommandConfiguration containing the command name, abstract description, and sub-command hierarchy.

For example, RuntimeLinuxHelper.swift defines the core container run, container build, and container create commands as distinct types. This modular approach allows the CLI to group related functionality while maintaining clear separation between runtime operations and network management.

Option Parsing and Validation

Flags such as -e/--env, --cpus, --memory, and --mount appear as property declarations within command structs using ArgumentParser wrappers:

• @Option for named values with arguments
• @Flag for boolean toggles
• @Argument for positional parameters

ArgumentParser automatically validates types—rejecting non-numeric strings for --cpus, for instance—and generates formatted help output without additional code.

Core Command Groups

The CLI organizes functionality into logical groups that mirror standard container workflows:

Process Management

The container run command starts containers in foreground or detached mode, accepting image references and command arguments.

Image Building

The container build command constructs OCI images from Containerfiles, supporting custom Dockerfiles via -f and multiple tags via -t.

Lifecycle Control

Commands like container create, container start, container stop, and container rm manage container state independently of execution, allowing pre-configuration before runtime.

Execution

The container exec command runs additional processes inside active containers, useful for debugging or administrative tasks.

Networking

The container network sub-command group handles creation, inspection, and attachment of containers to custom network segments.

Inspection and Monitoring

Commands including container inspect, container logs, and container stats retrieve runtime metadata and resource utilization data.

Cleanup Operations

The container prune and container system prune commands remove unused images, containers, and networks to reclaim disk space.

Option Categories and Flag Reference

Options fall into distinct functional categories that control specific container behaviors:

Process Options

Flags like -e/--env, --uid, and -i/--interactive configure environment variables, user identities, and stdin attachment.

Resource Constraints

The -c/--cpus and -m/--memory flags limit computational resources, accepting numeric values that ArgumentParser validates before execution.

Management Settings

--cidfile persists container IDs to files, --init enables an init process, and --runtime selects alternative container runtimes.

Networking Configuration

--dns sets nameservers, --network attaches to specific networks, and --publish exposes container ports to the host.

Registry Protocols

The --scheme flag accepts http, https, or auto values for registry communication.

Progress Reporting

--progress controls output formatting with options including auto, ansi, plain, and color.

Practical CLI Usage Examples

The following patterns demonstrate common workflows supported by the command-line interface:

# Run an interactive shell with TTY allocation

container run -it ubuntu:latest /bin/bash

# Start a detached web server with port mapping

container run -d --name web -p 8080:80 nginx:latest

# Build with a custom Dockerfile and multiple tags

container build -f docker/Dockerfile.prod \
                -t my-app:prod \
                -t my-app:latest .

# Create then start a container for pre-configuration

container create --name mydb postgres:15
container start mydb

# Execute a backup command inside a running database

container exec mydb pg_dumpall -U postgres > all.sql

# Mount and publish a Unix socket between host and container

container run --mount type=bind,source=/tmp/host.sock,target=/tmp/container.sock \
              --publish-socket /tmp/host.sock:/tmp/container.sock \
              my-image

# Use a custom init image for boot-time setup

container run --init-image local/custom-init:latest \
              --init \
              ubuntu:latest my-app

Key Source Files for CLI Understanding

Understanding the implementation requires examining specific files that define the command structure:

• docs/command-reference.md — The authoritative markdown reference listing every command, flag, and usage example, generated from source code annotations.

• Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift — Implements core sub-commands including run, build, and create as AsyncParsableCommand conforming types.

• Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift — Defines networking-related commands such as network create and network attach.

• Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift — Handles communication with the container-runtime-linux daemon, bridging CLI arguments to runtime operations.

• Package.swift — Declares the executable target, ArgumentParser dependency, and build configuration for the container binary.

Summary

• The Apple/container CLI uses Swift ArgumentParser to define commands as AsyncParsableCommand structs with declarative property wrappers for options.
• Command implementations reside in Sources/Plugins/*Helper.swift files, while runtime logic delegates to RuntimeClient.swift.
• The interface supports standard container workflows including process execution, image building, lifecycle management, and networking.
• Options are categorized by function—process, resource, management, networking, registry, and progress—with automatic type validation.
• Reference documentation in docs/command-reference.md provides the complete command specification and usage examples.

Frequently Asked Questions

How does the apple/container CLI parse command-line arguments?

The CLI uses the Swift ArgumentParser framework, where each command is a struct conforming to AsyncParsableCommand. Arguments are declared as properties using @Option, @Flag, or @Argument wrappers, which automatically handle parsing, type validation, and help generation without manual string processing.

Where are the container run and build commands defined?

These commands are implemented in Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift. This file contains the AsyncParsableCommand conforming types that define the run, build, create, and other core sub-commands, including their CommandConfiguration and option declarations.

What file handles communication with the container runtime?

The Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift file manages communication with the container-runtime-linux daemon. After the CLI parses arguments, the command implementations call into this client to execute container operations.

How can I view the complete list of available commands and flags?

The authoritative reference is located at docs/command-reference.md in the repository root. This file contains the full documentation for every command, option, and example, and is maintained in sync with the source code implementation.

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