Apple Container Commands: Complete CLI Reference for the apple/container Repository

The apple/container repository provides a comprehensive Swift-based CLI tool with 50+ commands organized into nine functional categories including container lifecycle, image management, network operations, and system administration.

The apple/container repository is Apple's open-source container management tool built with Swift and the swift-argument-parser library. This command-line interface provides extensive functionality for running containers, managing images, configuring networks, and controlling the container runtime daemon. Understanding the available apple container commands helps developers effectively orchestrate containerized workloads across macOS and Linux environments.

Container Lifecycle Commands

The apple container CLI provides comprehensive control over container instances through the container subcommand family. Each command is implemented as a separate struct conforming to AsyncLoggableCommand in the Sources/ContainerCommands/Container/ directory.

Core container operations include:

• run - Create and start a container (implemented in ContainerRun.swift)
• create - Create a container without starting it (ContainerCreate.swift)
• start - Start one or more stopped containers (ContainerStart.swift)
• stop - Gracefully stop running containers (ContainerStop.swift)
• kill - Send SIGKILL to containers (ContainerKill.swift)
• delete (alias rm) - Remove containers (ContainerDelete.swift)
• list (alias ls) - List all containers (ContainerList.swift)
• exec - Run commands in running containers (ContainerExec.swift)
• logs - Fetch container logs (ContainerLogs.swift)
• inspect - Display detailed container information (ContainerInspect.swift)
• stats - Show resource usage statistics (ContainerStats.swift)
• prune - Remove unused containers (ContainerPrune.swift)
• export - Export container filesystems (ContainerExport.swift)
• copy (alias cp) - Copy files between containers and the local filesystem (ContainerCopy.swift)

Image Management Commands

Image operations are grouped under the container image subcommand namespace, with implementations located in Sources/ContainerCommands/Image/. These commands support OCI-compliant image handling.

Available image commands:

• list (alias ls) - List local images (ImageList.swift)
• pull - Download images from registries (ImagePull.swift)
• push - Upload images to registries (ImagePush.swift)
• save - Save images to tar archives (ImageSave.swift)
• load - Load images from tar archives (ImageLoad.swift)
• tag - Tag images with new references (ImageTag.swift)
• inspect - Display image metadata (ImageInspect.swift)
• delete (alias rm) - Remove images (ImageDelete.swift)
• prune - Remove unused images (ImagePrune.swift)

Network and Volume Management Commands

The CLI provides infrastructure management capabilities for networking and persistent storage.

Network commands (Sources/ContainerCommands/Network/):

• create - Create networks (NetworkCreate.swift)
• delete (alias rm) - Remove networks (NetworkDelete.swift)
• list (alias ls) - List networks (NetworkList.swift)
• inspect - Display network details (NetworkInspect.swift)
• prune - Remove unused networks (NetworkPrune.swift)

Volume commands (Sources/ContainerCommands/Volume/):

• create - Create volumes (VolumeCreate.swift)
• delete (alias rm) - Remove volumes (VolumeDelete.swift)
• list (alias ls) - List volumes (VolumeList.swift)
• inspect - Display volume details (VolumeInspect.swift)
• prune - Remove unused volumes (VolumePrune.swift)

Machine and System Commands

The tool manages virtual machine backends and daemon-level configuration through specialized command groups.

Machine (VM) commands (Sources/ContainerCommands/Machine/):

• create - Create VM instances (MachineCreate.swift)
• run - Run commands inside VMs (MachineRun.swift)
• list (alias ls) - List VMs (MachineList.swift)
• inspect - Display VM details (MachineInspect.swift)
• set - Configure VM properties (MachineSet.swift)
• set-default - Set default VM (MachineSetDefault.swift)
• logs - Fetch VM logs (MachineLogs.swift)
• stop - Stop VMs (MachineStop.swift)
• delete (alias rm) - Remove VMs (MachineDelete.swift)

System commands (Sources/ContainerCommands/System/):

• start - Start the container daemon (SystemStart.swift)
• stop - Stop the container daemon (SystemStop.swift)
• status - Check daemon status (SystemStatus.swift)
• version - Display version information (SystemVersion.swift)
• logs - Fetch daemon logs (SystemLogs.swift)
• df - Show disk usage (SystemDF.swift)
• property list - List system properties (SystemProperty.swift)
• kernel set - Set custom kernels (SystemKernel.swift)
• dns create/delete/list - Manage DNS configuration (SystemDNS.swift)

Registry and Builder Commands

Specialized commands handle authentication and image building infrastructure.

Registry authentication (Sources/ContainerCommands/Registry/):

• login - Authenticate with registries (RegistryLogin.swift)
• logout - Remove registry credentials (RegistryLogout.swift)
• list - List authenticated registries (RegistryList.swift)

Builder control (Sources/ContainerCommands/Builder/):

• start - Start the build engine (BuilderStart.swift)
• status - Check builder status (BuilderStatus.swift)
• stop - Stop the build engine (BuilderStop.swift)
• delete (alias rm) - Remove builder instances (BuilderDelete.swift)

Command Architecture and Implementation

All apple container commands are implemented as Swift structs conforming to the AsyncLoggableCommand protocol, enabling asynchronous execution with integrated logging. The Application type in Sources/ContainerCommands/Application.swift discovers these structs at startup and registers them via CommandConfiguration.

Key architectural patterns:

• Modular definitions - Each command resides in its own file under Sources/ContainerCommands/ with clear naming conventions (e.g., ContainerRun.swift, ImagePull.swift)
• Shared flag groups - Common options are defined in Sources/ContainerCommands/Flags/ and reused across commands via @OptionGroup, including processFlags, resourceFlags, managementFlags, registryFlags, and progressFlags
• Async execution - Commands leverage Swift concurrency for non-blocking container API calls while maintaining progress-bar UI feedback
• Error translation - Internal errors convert to ContainerizationError or ArgumentParser.ExitCode values for consistent CLI exit statuses

Usage Examples

Run an interactive container with volume mounting:

container run -it -v $(pwd):/workspace ubuntu:latest /bin/bash

Build and tag an image from the current directory:

container build -t myapp:latest .

Create a custom network and attach a container:

container network create mynet
container run --network mynet -p 8080:80 nginx:latest

Manage the container system daemon:

container system start
container system status

Configure a custom kernel for the runtime:

container system kernel set --arch arm64 --binary /path/to/vmlinuz

Authenticate with a private registry:

container registry login myregistry.example.com

Summary

• The apple/container repository provides 50+ CLI commands organized into nine functional categories: container lifecycle, image management, network operations, volume operations, machine handling, builder control, registry authentication, system administration, and utilities.
• Each command is implemented as a Swift struct in Sources/ContainerCommands/ conforming to AsyncLoggableCommand, with automatic registration managed by Application.swift.
• Shared flag definitions in Sources/ContainerCommands/Flags/ ensure consistent option handling across related commands.
• The CLI supports both standard Docker-compatible workflows (run, build, pull, push) and Apple-specific extensions (machine management, kernel configuration, DNS management).

Frequently Asked Questions

How do I list all available commands in the apple/container CLI?

Run container --help or container help to display the complete command tree. The HelpCommand.swift file implements this functionality, and the Application struct in Sources/ContainerCommands/Application.swift automatically discovers all registered subcommands at runtime, including aliases like ls for list and rm for delete.

What is the difference between container stop and container kill?

The stop command (implemented in ContainerStop.swift) sends a graceful shutdown signal (SIGTERM) and waits for the container to exit, while kill (implemented in ContainerKill.swift) immediately sends SIGTERM or a specified signal to force termination without cleanup time. Use stop for graceful shutdowns and kill for unresponsive processes.

Where are the command implementations located in the source code?

Command implementations reside in Sources/ContainerCommands/ with subdirectories for each functional area: Container/ for runtime commands, Image/ for image management, Network/ and Volume/ for infrastructure, Machine/ for VM operations, System/ for daemon control, Builder/ for image building, and Registry/ for authentication. The entry point is Sources/CLI/ContainerCLI.swift.

How does the CLI handle asynchronous operations?

All commands conform to AsyncLoggableCommand, defined in the codebase, which allows them to execute asynchronous container API calls while automatically handling logging and progress-bar UI. This architecture enables concurrent operations like pull and push to display real-time progress without blocking the terminal.

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