How to List Containers Using the Apple Container CLI: Command Reference and Implementation Guide

Use container list to display running containers, add --all to include stopped ones, and use --format json or --quiet for scriptable output.

The container command-line tool is the primary interface for managing containers in the apple/container open-source project. When you need to enumerate containers, the CLI communicates with the container management daemon via a gRPC-based API to retrieve a consistent snapshot of the current state. This article explains how to use the list command effectively and how the underlying Swift implementation ensures thread-safe, atomic container enumeration.

How the Container List Command Works

The container list command follows a client-server architecture that separates the CLI front-end from the daemon back-end.

When you execute a list command, the CLI parses your arguments and constructs a ContainerListRequest. This request travels over gRPC to the daemon's ContainersService, which maintains an in-memory map of all container snapshots ([String: ContainerState]).

To prevent race conditions during enumeration, the service wraps the operation in an asynchronous lock (AsyncLock). The helper method withContainerList, defined in Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift, extracts a consistent array of ContainerSnapshot objects and passes them to the caller. This guarantees that your output reflects a single point in time, even if other processes create or destroy containers concurrently.

Basic Commands for Listing Containers

By default, the container list command shows only running containers. The daemon returns the snapshot data, which the CLI then formats according to your specifications.

Show currently running containers:

container list

Display all containers including stopped ones:

container list --all

Print only container IDs (useful for piping to other commands):

container list --quiet

Filtering and Formatting Output

The Apple Container CLI supports multiple output formats to accommodate both human reading and automation pipelines.

Available formats include table (default), JSON, YAML, and TOML. Control the output using the --format flag:

# Output as JSON for script consumption

container list --format json

Combine flags to create precise queries. For example, to generate a machine-readable list of all container IDs:

container list --all --format json --quiet

The formatting logic resides in Sources/ContainerCommands/OutputRendering.swift, which handles the conversion from internal ContainerSnapshot objects to your chosen display format.

Understanding the Implementation Details

The atomic list operation is implemented in Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift at lines 17-27. The withContainerList method acquires an AsyncLock before accessing the container map, ensuring that the enumeration sees a stable view even under concurrent modification.

According to the official documentation in docs/command-reference.md (lines 36-48), the list sub-command accepts the following key flags:

• --all or -a: Include stopped containers in the output
• --quiet or -q: Display only container IDs
• --format: Specify output format (table, json, yaml, toml)

The gRPC protocol ensures that the CLI remains lightweight while the daemon maintains the authoritative state, following the architecture described in the apple/container repository source code.

Summary

• Use container list to see running containers or container list --all to include stopped ones
• The --quiet flag outputs only container IDs, ideal for shell scripting
• Output formats include table (default), JSON, YAML, and TOML via --format
• The daemon uses AsyncLock and withContainerList in ContainersService.swift to provide atomic, consistent snapshots
• The CLI communicates via gRPC to the ContainersService, which manages the in-memory [String: ContainerState] map

Frequently Asked Questions

How do I list all containers including stopped ones?

Add the --all flag (or -a) to your command: container list --all. By default, the command filters to show only running containers, but this flag instructs the daemon's ContainersService to include stopped container snapshots in the response.

What output formats does container list support?

The command supports table (human-readable default), JSON, YAML, and TOML. Specify your preferred format using --format json or similar. The formatting is handled by Sources/ContainerCommands/OutputRendering.swift, which serializes the ContainerSnapshot array returned by the daemon.

How does the Apple Container CLI ensure consistent list output?

The daemon implements an atomic snapshot mechanism using withContainerList in ContainersService.swift. This method acquires an AsyncLock before reading the in-memory container map ([String: ContainerState]), ensuring the enumeration captures a single point-in-time view even if other operations modify containers concurrently.

Can I use container list output in shell scripts?

Yes. Use the --quiet or -q flag to print only container IDs, one per line, which you can pipe to other commands like xargs or docker rm. For structured data, combine --quiet with --format json to get a JSON array of IDs that parsers like jq can process reliably.

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