# How to Understand the Apple/Container Command-Line Interface: Architecture and Usage > Learn the Apple/container command-line interface architecture and usage. Understand Swift, ArgumentParser, plugin helpers, and service clients for effective operation. - Repository: [Apple/container](https://github.com/apple/container) - Tags: architecture - Published: 2026-07-06 --- **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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Package.swift), which declares the `container` target and its dependency on the Swift ArgumentParser library. When built, the package generates a [`main.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/RuntimeLinuxHelper.swift) and [`NetworkVmnetHelper.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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: ```bash # Run an interactive shell with TTY allocation container run -it ubuntu:latest /bin/bash ``` ```bash # Start a detached web server with port mapping container run -d --name web -p 8080:80 nginx:latest ``` ```bash # Build with a custom Dockerfile and multiple tags container build -f docker/Dockerfile.prod \ -t my-app:prod \ -t my-app:latest . ``` ```bash # Create then start a container for pre-configuration container create --name mydb postgres:15 container start mydb ``` ```bash # Execute a backup command inside a running database container exec mydb pg_dumpall -U postgres > all.sql ``` ```bash # 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 ``` ```bash # 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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/Plugins/RuntimeLinux/RuntimeLinuxHelper.swift)** — Implements core sub-commands including `run`, `build`, and `create` as `AsyncParsableCommand` conforming types. - **[`Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift`](https://github.com/apple/container/blob/main/Sources/Plugins/NetworkVmnet/NetworkVmnetHelper.swift)** — Defines networking-related commands such as `network create` and `network attach`. - **[`Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift`](https://github.com/apple/container/blob/main/Sources/Services/Runtime/RuntimeClient/RuntimeClient.swift)** — Handles communication with the container-runtime-linux daemon, bridging CLI arguments to runtime operations. - **[`Package.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.