# How to List Containers Using the Apple Container CLI: Command Reference and Implementation Guide > Learn to list containers using the Apple Container CLI. Discover commands to show running, stopped, or all containers with scriptable output options. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-06-23 --- **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`](https://github.com/apple/container/blob/main/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: ```bash container list ``` Display all containers including stopped ones: ```bash container list --all ``` Print only container IDs (useful for piping to other commands): ```bash 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: ```bash # 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: ```bash container list --all --format json --quiet ``` The formatting logic resides in [`Sources/ContainerCommands/OutputRendering.swift`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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.