Complete Guide to Apple Container Commands: CLI Reference and Source Implementation

The Apple Container CLI supports over 40 Docker-compatible commands organized into eight functional categories including container lifecycle, image management, builder operations, network configuration, volume handling, registry authentication, VM machine management, and system administration.

The apple/container repository provides a Docker-compatible command-line interface for macOS that enables users to run and manage Linux containers natively. Understanding the complete set of apple container commands available in this tool helps developers leverage its full capabilities, from basic container operations to advanced VM management and system-level configuration. Each command maps to specific implementation files in the Sources/ directory, with comprehensive documentation available in docs/command-reference.md.

Container Lifecycle Commands

The container lifecycle category provides the core functionality for creating, running, and managing containers. These commands are implemented primarily in the Sources/ContainerXPC/ directory.

Running and Creating Containers

container run starts a container from an image in the foreground by default. It handles process, resource, and management flags through the XPC client session. The implementation resides in Sources/ContainerXPC/XPCClientSession.swift with argument parsing in main.swift.

container create creates a stopped container using the same flags as run but without starting it. It shares the same XPC client implementation path as the run command.

container start starts a previously created container and optionally attaches to it. The server-side logic is found in Sources/ContainerXPC/XPCServerSession.swift.

Stopping and Removing Containers

container stop gracefully stops a running container by sending SIGTERM followed by an optional SIGKILL. This is implemented in Sources/ContainerXPC/XPCServer.swift.

container kill sends an immediate signal to a container, defaulting to KILL. The signal handling logic is defined in Sources/ContainerXPC/XPCMessage.swift.

container delete (alias rm) removes one or more containers with an optional --force flag. The implementation is located in Sources/ContainerXPC/XPCServer.swift.

container prune removes all stopped containers and reports reclaimed space, also implemented in XPCServer.swift.

Monitoring and Debugging

container list (alias ls) shows containers with multiple output format options including json, yaml, toml, and table. The formatting logic is handled by Sources/TerminalProgress/ProgressTaskCoordinator.swift.

container exec executes a new process inside a running container, reusing the same process flags as run. The client implementation is in Sources/ContainerXPC/XPCClientSession.swift.

container logs streams or tails a container's stdout/stderr or boot log. The message handling is implemented in Sources/ContainerXPC/XPCMessage.swift.

container inspect prints container JSON metadata, implemented in Sources/ContainerXPC/XPCServer.swift.

container stats displays real-time resource usage including CPU, memory, and network statistics. The rendering uses Sources/TerminalProgress/ProgressBar.swift.

Data Management

container export saves a stopped container's filesystem as a tar stream. The implementation is in Sources/ContainerXPC/XPCServerSession.swift.

container copy (alias cp) copies files between the host and a running container. The client-side implementation is in Sources/ContainerXPC/XPCClientSession.swift.

Image Management Commands

Image management commands handle the storage, transfer, and inspection of container images. These operations are implemented primarily in Sources/ContainerPersistence/.

Listing and Inspecting Images

container image list (alias ls) lists local images with optional verbosity and format flags. The implementation uses Sources/ContainerPersistence/EntityStore.swift.

container image inspect shows detailed JSON information for images, also implemented in EntityStore.swift.

Transferring Images

container image pull pulls an image from a registry, supporting flags for --scheme, --platform, and --progress. The configuration loading is handled by Sources/ContainerPersistence/ConfigurationLoader.swift.

container image push pushes a local image to a registry, sharing the same loader implementation as pull.

container image save saves one or more images to a tar archive. The implementation references Sources/ContainerPersistence/MemorySize.swift for resource management.

container image load loads images from a tar archive using the --input flag. Parsing logic is in Sources/ContainerPersistence/Parsers.swift.

Image Maintenance

container image tag tags an existing image with a new reference. The implementation uses Sources/ContainerPersistence/PathUtils.swift.

container image delete (alias rm) deletes one or more images with --force and --all options. The state management is handled by EntityStore.swift.

container image prune removes dangling or unused images, with the -a flag removing all unreferenced images. This is implemented in EntityStore.swift.

Builder Management Commands

Builder commands manage the BuildKit builder container used for building images. These are implemented in BuilderManagement.swift (generated from the Makefile).

Builder Lifecycle

container builder start starts the BuildKit builder container that powers container build operations.

container builder status shows the builder status and supports --format flags for output customization.

container builder stop stops the builder container.

container builder delete (alias rm) deletes the builder container, with a --force option if the builder is currently running.

Network Management Commands

Network management commands are available on macOS 26 and later. These are implemented in Sources/NetworkManager.swift.

Network Operations

container network create creates a user-defined network with optional driver options. You can specify subnets and other configuration parameters.

container network delete (alias rm) deletes one or more networks, with an --all flag to remove all user-defined networks.

container network prune removes unused networks while preserving system defaults.

container network list (alias ls) lists user-defined networks with format flags for output customization.

container network inspect shows detailed JSON information for networks.

Volume Management Commands

Volume commands manage persistent storage for containers. These are implemented in Sources/VolumeStore.swift.

Volume Operations

container volume create creates a named volume supporting --label, --opt, and size flags.

container volume delete (alias rm) deletes volumes, with --all removing all volumes.

container volume prune removes volumes with no container references.

container volume list (alias ls) lists volumes with format options.

container volume inspect prints volume metadata as JSON.

Registry Management Commands

Registry commands handle authentication with container registries. These are implemented in Sources/RegistryAuth.swift.

Authentication Operations

container registry login stores credentials for a registry, supporting --password-stdin for secure password input.

container registry logout removes stored credentials for a registry.

container registry list lists known registries with format flags.

Container Machine (VM) Management Commands

Machine commands manage lightweight VMs for running containers. These are implemented in Sources/MachineManager.swift.

Machine Lifecycle

container machine create spins up a lightweight VM from an image, configurable with CPUs, memory, home-mount, and nested virtualization options.

container machine run executes a command inside a machine, booting it if necessary.

container machine list (alias ls) lists all machines with the default machine highlighted.

container machine inspect shows machine JSON metadata.

Machine Configuration

container machine set alters persistent machine settings such as CPU count and memory allocation.

container machine set-default marks a machine as the default for commands that omit the -n flag.

container machine logs streams or tails machine logs with --boot and --follow options.

Machine Control

container machine stop stops a running machine.

container machine delete (alias rm) deletes a machine, stopping it first if necessary.

System Management Commands

System commands manage the container runtime services and host configuration on macOS. These are implemented in Sources/SystemManager.swift, with specialized handlers in Sources/DNSHandler.swift, Sources/KernelInstaller.swift, and Sources/ContainerSystemConfig.swift.

Service Management

container system start starts the container-apiserver and background services, optionally installing a default kernel.

container system stop stops services, optionally using a launch-d prefix.

container system status health-checks the apiserver and prints JSON or table status.

container system version shows CLI and server version information.

container system logs streams service logs with --follow and --last options.

System Maintenance

container system df shows disk usage summaries for images, containers, and volumes.

container system kernel set installs or updates the Linux kernel used by the runtime via Sources/KernelInstaller.swift.

container system property list lists system properties in JSON or TOML format via Sources/ContainerSystemConfig.swift.

DNS Management

container system dns create, delete, and list manage local DNS domains for containers. These commands require sudo privileges and are implemented in Sources/DNSHandler.swift.

Practical Usage Examples

The following examples demonstrate common workflows using the apple container commands. All commands accept the --debug flag for verbose diagnostics.

# Run an interactive Ubuntu shell

container run -it ubuntu:latest /bin/bash

# Build and tag an image

container build -t myapp:latest .

# List all containers in JSON format

container list --format json

# Pull a multi-arch image, forcing the linux/amd64 variant

container image pull --platform linux/amd64 nginx:latest

# Create a custom network (macOS 26+)

container network create --subnet 192.168.200.0/24 mynet

# Create a VM-backed container machine with nested virtualization

container machine create alpine:3.22 --cpus 4 --memory 8G --virtualization --kernel ./vmlinux-kvm

# Export a stopped container's filesystem

container export -o mycontainer.tar mycontainer

# Prune unused images and volumes

container image prune -a
container volume prune

Summary

The Apple Container CLI organizes functionality into eight distinct command categories that mirror the source code structure:

• Container Lifecycle: Core operations including run, exec, logs, and export implemented in Sources/ContainerXPC/
• Image Management: Registry operations and local storage handled by Sources/ContainerPersistence/EntityStore.swift and related files
• Builder Management: BuildKit container control via BuilderManagement.swift
• Network Management: User-defined networking (macOS 26+) in Sources/NetworkManager.swift
• Volume Management: Persistent storage operations in Sources/VolumeStore.swift
• Registry Management: Authentication credentials in Sources/RegistryAuth.swift
• Machine Management: VM lifecycle control in Sources/MachineManager.swift
• System Management: Host-level services and configuration in Sources/SystemManager.swift and specialized handlers

Frequently Asked Questions

What is the difference between container delete and container prune?

container delete (or rm) removes specific containers by name or ID, while container prune removes all stopped containers automatically. The delete command supports --force to remove running containers, whereas prune focuses on cleanup and reports reclaimed disk space. Both are implemented in Sources/ContainerXPC/XPCServer.swift.

Which apple container commands require macOS 26 or later?

The network management commands (container network create, delete, prune, list, and inspect) require macOS 26 or later. These commands are implemented in Sources/NetworkManager.swift and provide user-defined networking capabilities not available in earlier macOS versions.

How does Apple Container handle registry authentication?

Authentication is managed through container registry login and logout commands, implemented in Sources/RegistryAuth.swift. The login command supports --password-stdin for secure credential input, storing credentials for subsequent push and pull operations against specific registries.

Where is the complete command reference documented?

The authoritative documentation lives in docs/command-reference.md within the repository. This file serves as the single source of truth for user-facing documentation, while the Swift Package definition in Package.swift organizes the underlying source modules that implement each command.

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