# Command-Line Interface for Managing Containers with Apple Container > Manage OCI containers on Apple Silicon with the native Swift `container` CLI. Control images, lifecycle, and run containers directly from your terminal. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-01 --- **Yes, the `container` CLI provides a native Swift-based command-line interface for managing containers, enabling system control, image operations, and full lifecycle management of OCI-compatible Linux containers on macOS Apple Silicon.** The `apple/container` repository delivers a complete command-line interface for managing containers directly from the terminal. This native Swift tool serves as the primary user entry point, translating sub-commands into calls to the underlying Containerization framework that drives the Apple Virtualization hypervisor and the vmnet networking stack. ## CLI Architecture and Implementation The command-line interface is architected as a thin façade over the runtime's Swift APIs. According to [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift), the CLI depends on Swift's **ArgumentParser** library to handle sub-command parsing, flag validation, and dispatch logic. The architecture follows a layered approach: - **CLI front-end** ([`Package.swift`](https://github.com/apple/container/blob/main/Package.swift)): Parses sub-commands and dispatches to runtime APIs. - **Containerization package**: Provides Swift APIs for image manipulation and container creation. - **Virtualization back-end**: Leverages Apple's Virtualization framework via the `container` Swift package. - **Networking layer** (`Sources/SocketForwarder`): Manages vmnet interfaces, port forwarding, and DNS services. - **Persistence layer** (`Sources/ContainerPersistence`): Stores container state, volumes, and configuration on disk. Long-running operations display progress bars implemented in `Sources/TerminalProgress`, which coordinates real-time terminal feedback while the runtime processes filesystem and network I/O. ## System Control Commands Before running containers, you must start the background service that hosts all containers using the `system` sub-command: ```bash # Start the container service container system start # Stop the background service container system stop ``` ## Image Management Operations The CLI provides first-class support for OCI registry operations, allowing you to pull, build, and push images. To pull an image from any OCI-compliant registry: ```bash container image pull docker.io/library/ubuntu:latest ``` Building images from Dockerfiles uses the `build` sub-command: ```bash container build -t myapp:1.0 . ``` Push operations distribute images to remote registries: ```bash container image push myregistry.example.com/myapp:1.0 ``` ## Container Lifecycle Management Create and run containers using the `run` command, which supports port mapping, volume mounts, and resource limits: ```bash # Create and start an interactive container with port forwarding container run --name my-ubuntu \ --publish 8080:80 \ --volume ~/mydata:/data \ docker.io/library/ubuntu:latest \ /bin/bash ``` Monitor active containers with the `ps` shortcut: ```bash container ps # Equivalent to `container container list --running` ``` Stop and remove containers using dedicated sub-commands: ```bash container stop my-ubuntu container rm my-ubuntu ``` ## Resource Configuration Options The CLI exposes flags for **resource configuration**, including CPU and memory limits, port exposure via `--publish`, and volume mounting via `--volume`. These options map directly to the underlying Containerization API that configures the Apple Virtualization framework parameters. ## Summary - The `container` CLI is a native Swift application built on the ArgumentParser library, declared in [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift). - It provides sub-commands for **system control** (`system start/stop`), **image management** (`image pull/push/build`), and **container lifecycle** (`run`, `ps`, `stop`, `rm`). - The interface acts as a thin façade over the Containerization Swift package, which manages virtualization via Apple Virtualization and networking via `Sources/SocketForwarder`. - State persistence is handled by `Sources/ContainerPersistence`, while progress reporting is implemented in `Sources/TerminalProgress`. - All command syntax is documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), while architectural details appear in [`docs/technical-overview.md`](https://github.com/apple/container/blob/main/docs/technical-overview.md). ## Frequently Asked Questions ### How do I start the container service before running containers? You must start the background system service using `container system start` before executing any container operations. This initializes the virtualization environment and networking stack required to host Linux containers on macOS. ### Where is the full command reference documented? The complete list of sub-commands, flags, and usage patterns resides in the repository's [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) file. This document provides authoritative syntax for all CLI operations including advanced resource configuration options. ### What programming language is the CLI built with? The CLI is written in Swift and uses Apple's **ArgumentParser** library for command-line parsing, as specified in the [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) manifest. It interfaces with the underlying runtime through the Containerization Swift package, which implements the virtualization and filesystem layers. ### Does the CLI support building images from Dockerfiles? Yes, the `container build` command supports building OCI-compatible images from Dockerfiles. The CLI processes the build context locally and stores the resulting image in the local container store, ready for execution or pushing to remote registries.