# Apple Container CLI Reference: Complete Command Guide

> Explore the complete Apple Container CLI command guide. Access the comprehensive reference in the apple/container repository to streamline your container management tasks.

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

---

**Yes, the apple/container repository provides a comprehensive CLI reference documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) and implemented in Swift using the swift-argument-parser library.**

The apple/container project delivers a full-featured command-line interface for managing containers on Apple platforms. This **Container CLI reference** documents every sub-command, flag, and usage pattern derived directly from the Swift source code. The authoritative documentation is automatically generated and maintained in the repository's [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) file, ensuring it remains synchronized with the implementation.

## CLI Reference Architecture and Entry Point

The CLI architecture centers on asynchronous command parsing and modular sub-command dispatch.

### Main Entry Point (ContainerCLI.swift)

The CLI entry point is the `ContainerCLI` struct defined in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift). This struct conforms to `AsyncParsableCommand` from the swift-argument-parser library, enabling asynchronous argument parsing and command execution.

### Command Dispatch (Application.swift)

When the binary is invoked, `Application.main()` in [`Sources/ContainerCommands/Application.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Application.swift) parses top-level arguments, validates them, and dispatches execution to the appropriate sub-command implementation within the **ContainerCommands** module.

## Command Structure and Sub-commands

The CLI follows standard docker-like syntax while adding Apple-specific extensions. The ContainerCommands module organizes functionality into logical command groups:

### Core Container Workflow

- `container run`, `container build`, `container create`
- `container start`, `container stop`, `container exec`

### Image Management

- `container image pull`, `container image push`
- `container image tag`, `container image prune`

### Machine Management

- `container machine create`, `container machine run`
- `container machine list`, `container machine set-default`

### System and Infrastructure

- `container system start`, `container system status`, `container system version`
- `container network create`, `container volume create`, `container volume prune`

## Apple-Specific CLI Extensions

The CLI extends standard container commands with Apple-specific flags including `--rosetta` for Rosetta 2 emulation, `--virtualization` for virtualization framework options, and custom kernel support. These extensions integrate tightly with the container stack via internal APIs, XPC services, and persistence layers wired through the [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) manifest.

## Accessing the Official CLI Reference

The definitive **Container CLI reference** lives in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) at the repository root. This markdown file is automatically generated from the codebase and kept in sync with command definitions. It documents all commands, flags, and output formats across sections including *Core Commands*, *Image Management*, *Container Machine Management*, and *System Management*.

## Practical Usage Examples

```bash

# Run a container interactively

container run -it ubuntu:latest /bin/bash

# Build an image and tag it

container build -t myapp:latest .

# Create a container machine and set it as default

container machine create --cpus 4 --memory 8G alpine:3.22 --name dev-machine --set-default

# List all running containers

container list

# Pull an image from a private registry using HTTPS

container image pull --scheme https registry.example.com/myimage:1.2.3

# Show system version with JSON output

container system version --format json

```

## Package Integration

The `container` executable target is declared in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift), linking the CLI to the swift-argument-parser dependency and the broader container stack. Each sub-command implementation resides in individual Swift files under `Sources/ContainerCommands/`, mirroring the high-level operations exposed in the CLI reference.

## Summary

- The **apple/container CLI reference** is fully documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) and automatically generated from the Swift source code.
- The entry point `ContainerCLI` in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift) uses `AsyncParsableCommand` for asynchronous parsing.
- `Application.main()` in [`Sources/ContainerCommands/Application.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Application.swift) dispatches commands to specific implementations.
- Commands cover core workflows, image management, machine management, and system utilities with Apple-specific extensions like `--rosetta` and `--virtualization`.
- The CLI is built as a Swift package executable with dependencies defined in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift).

## Frequently Asked Questions

### Where is the official CLI reference documentation for apple/container?

The official CLI 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 complete documentation for every sub-command, flag, and usage example, and it is automatically generated from the Swift source code to ensure it stays synchronized with the actual implementation.

### What library does the apple/container CLI use for command parsing?

The CLI uses the **swift-argument-parser** library. The main entry point is the `ContainerCLI` struct in [`Sources/CLI/ContainerCLI.swift`](https://github.com/apple/container/blob/main/Sources/CLI/ContainerCLI.swift), which conforms to `AsyncParsableCommand` to enable asynchronous argument parsing and command execution.

### How does the CLI dispatch commands to their implementations?

Command dispatch occurs through `Application.main()` in [`Sources/ContainerCommands/Application.swift`](https://github.com/apple/container/blob/main/Sources/ContainerCommands/Application.swift). This method parses top-level arguments, validates them, and routes execution to the appropriate sub-command implementation within the ContainerCommands module.

### Does the apple/container CLI support Docker-compatible commands?

Yes, the CLI follows standard docker-like syntax for commands such as `run`, `build`, `pull`, and `push`. It also adds Apple-specific extensions including `--rosetta` for Rosetta 2 support and `--virtualization` flags for enhanced integration with Apple Silicon and virtualization frameworks.