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

> Explore the complete Apple Container CLI reference. Discover over 40 Docker-compatible commands for container lifecycle, image management, networking, volumes, and more. Understand the apple/container source implementation.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: api-reference
- Published: 2026-07-06

---

**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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerXPC/XPCClientSession.swift) with argument parsing in [`main.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerXPC/XPCServer.swift).

**container prune** removes all stopped containers and reports reclaimed space, also implemented in [`XPCServer.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerXPC/XPCMessage.swift).

**container inspect** prints container JSON metadata, implemented in [`Sources/ContainerXPC/XPCServer.swift`](https://github.com/apple/container/blob/main/Sources/ContainerXPC/XPCServer.swift).

**container stats** displays real-time resource usage including CPU, memory, and network statistics. The rendering uses [`Sources/TerminalProgress/ProgressBar.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/EntityStore.swift).

**container image inspect** shows detailed JSON information for images, also implemented in [`EntityStore.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/Parsers.swift).

### Image Maintenance

**container image tag** tags an existing image with a new reference. The implementation uses [`Sources/ContainerPersistence/PathUtils.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/EntityStore.swift).

**container image prune** removes dangling or unused images, with the `-a` flag removing all unreferenced images. This is implemented in [`EntityStore.swift`](https://github.com/apple/container/blob/main/EntityStore.swift).

## Builder Management Commands

Builder commands manage the BuildKit builder container used for building images. These are implemented in [`BuilderManagement.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/SystemManager.swift), with specialized handlers in [`Sources/DNSHandler.swift`](https://github.com/apple/container/blob/main/Sources/DNSHandler.swift), [`Sources/KernelInstaller.swift`](https://github.com/apple/container/blob/main/Sources/KernelInstaller.swift), and [`Sources/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Sources/KernelInstaller.swift).

**container system property list** lists system properties in JSON or TOML format via [`Sources/ContainerSystemConfig.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.

```bash

# 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`](https://github.com/apple/container/blob/main/Sources/ContainerPersistence/EntityStore.swift) and related files
- **Builder Management**: BuildKit container control via [`BuilderManagement.swift`](https://github.com/apple/container/blob/main/BuilderManagement.swift)
- **Network Management**: User-defined networking (macOS 26+) in [`Sources/NetworkManager.swift`](https://github.com/apple/container/blob/main/Sources/NetworkManager.swift)
- **Volume Management**: Persistent storage operations in [`Sources/VolumeStore.swift`](https://github.com/apple/container/blob/main/Sources/VolumeStore.swift)
- **Registry Management**: Authentication credentials in [`Sources/RegistryAuth.swift`](https://github.com/apple/container/blob/main/Sources/RegistryAuth.swift)
- **Machine Management**: VM lifecycle control in [`Sources/MachineManager.swift`](https://github.com/apple/container/blob/main/Sources/MachineManager.swift)
- **System Management**: Host-level services and configuration in [`Sources/SystemManager.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/Package.swift) organizes the underlying source modules that implement each command.