Apple Container CLI Reference: Complete Command Guide

Yes, the apple/container repository provides a comprehensive CLI reference documented in 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 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. 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 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 manifest.

Accessing the Official CLI Reference

The definitive Container CLI reference lives in 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

# 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, 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 and automatically generated from the Swift source code.
• The entry point ContainerCLI in Sources/CLI/ContainerCLI.swift uses AsyncParsableCommand for asynchronous parsing.
• Application.main() in 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.

Frequently Asked Questions

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

The official CLI reference is located at 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, 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. 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.

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