# What Is the Command Reference File in apple/container? Purpose and Usage Guide > Learn the purpose of the command reference file in apple/container. This guide details every sub-command, flag, and usage example for the Container CLI. - Repository: [Apple/container](https://github.com/apple/container) - Tags: api-reference - Published: 2026-07-06 --- **The [`command-reference.md`](https://github.com/apple/container/blob/main/command-reference.md) file serves as the single source of truth for the Container CLI, documenting every sub-command, flag, and usage example in the apple/container repository.** The [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) file bridges the Swift implementation and end-user documentation for the Container CLI. Located in the `apple/container` repository, this Markdown file enumerates all top-level sub-commands—such as `run`, `build`, `image`, and `machine`—along with their accepted flags and illustrative snippets. Because the CLI is the primary user-facing component, maintaining an accurate command reference ensures developers can discover capabilities without reading source code. ## Core Purpose of the Command Reference File The command reference file functions as the **authoritative reference guide** for the Container CLI. It resides at [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) and provides a searchable, version-aware inventory of the entire command-line surface. When engineers add new flags or sub-commands in `Sources/ContainerCLI/...`, they update this file to keep the documented interface synchronized with the implementation. ## Five Architectural Roles of the Command Reference The file fulfills several critical functions beyond static documentation: ### Documentation Hub The file lives under `docs/` and renders on GitHub as the primary reference for all CLI capabilities. Users can search for specific flags or browse command categories without leaving the repository. ### Change-Driven Source When the Swift source code introduces new functionality—such as additional flags in `Sources/ContainerCLI/...`—developers append the corresponding entries to [`command-reference.md`](https://github.com/apple/container/blob/main/command-reference.md). This workflow ensures that code changes and documentation updates remain paired in the same commit history. ### Tool-Generation Input The [`scripts/make-docs.sh`](https://github.com/apple/container/blob/main/scripts/make-docs.sh) script ingests [`command-reference.md`](https://github.com/apple/container/blob/main/command-reference.md) when generating the published documentation site. This automation guarantees that the rendered docs always reflect the repository’s current state, eliminating manual copy-paste errors between source and documentation. ### Version-Aware Documentation A banner at the top of the file (lines 3–7) warns readers that the content reflects the **current branch** and redirects them to release-specific versions for stable documentation. This prevents users from accidentally using unreleased flags on production builds. ### CLI-Driven Testing The exhaustive list of flags provides a checklist for test suites. For example, [`Tests/ContainerBuildTests/BuilderExtensionsTests.swift`](https://github.com/apple/container/blob/main/Tests/ContainerBuildTests/BuilderExtensionsTests.swift) validates that each advertised `container build` option is accepted and behaves exactly as described in the reference. ## Documented CLI Commands and Examples The command reference contains runnable examples for every major operation. Below are typical invocations documented in the file: Run an interactive shell in an Ubuntu container: ```bash container run -it ubuntu:latest /bin/bash ``` *(Documented under "`container run`", lines 12–20)* Build an image with a custom Dockerfile and multiple tags: ```bash container build -f Dockerfile.prod -t my-app:prod -t my-app:latest . ``` *(Documented under "`container build`", lines 24–33)* List all containers in JSON format: ```bash container list --format json --all ``` *(Documented under "`container list (ls)`", lines 36–44)* Create a new container machine and set it as the default: ```bash container machine create --name dev-machine alpine:3.22 --set-default ``` *(Documented under "`container machine create`", lines 65–73)* ## Key Files Supporting the Command Reference Several files work together to maintain and publish the command reference: - **[`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md)** — The central Markdown document listing every CLI command, flag, and example. - **[`scripts/make-docs.sh`](https://github.com/apple/container/blob/main/scripts/make-docs.sh)** — The script that incorporates the reference file into the generated documentation site. - **`Sources/TerminalProgress/...`** — Swift source implementing progress-bar UI used by many CLI commands (relevant for the `--progress` flag documented in the reference). - **[`Tests/ContainerBuildTests/BuilderExtensionsTests.swift`](https://github.com/apple/container/blob/main/Tests/ContainerBuildTests/BuilderExtensionsTests.swift)** — Test suite that validates the behavior of the `container build` command and its flags against the documented specification. ## Summary - The **command reference file** at [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) is the definitive documentation for the Container CLI. - It serves as a **documentation hub**, **change-driven source**, **tool-generation input**, **version-aware guide**, and **testing checklist**. - The **[`make-docs.sh`](https://github.com/apple/container/blob/main/make-docs.sh)** script automatically publishes the file to the documentation site. - Examples for commands like `run`, `build`, `list`, and `machine` include exact flags and syntax validated by test suites. ## Frequently Asked Questions ### Where is the command reference file located in the apple/container repository? The file is located at [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) in the repository root. It is rendered automatically on GitHub and ingested by the documentation generation pipeline. ### How does the command reference stay synchronized with the Swift source code? Developers update [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) whenever they add new flags or sub-commands in `Sources/ContainerCLI/...`. This co-location of code and documentation in the same repository ensures that pull requests include both implementation and reference updates. ### What is the purpose of the version warning at the top of the command reference? The banner at lines 3–7 warns readers that the content reflects the **current branch** rather than a stable release. This directs users to version-specific documentation when they need instructions for a production build, preventing accidental use of unreleased features. ### How does the command reference support automated testing? Test suites such as [`Tests/ContainerBuildTests/BuilderExtensionsTests.swift`](https://github.com/apple/container/blob/main/Tests/ContainerBuildTests/BuilderExtensionsTests.swift) use the exhaustive flag listings in the reference as a checklist. Tests verify that each documented option is accepted by the CLI and behaves exactly as specified, ensuring the reference remains accurate.