What Is the Command Reference File in apple/container? Purpose and Usage Guide

The 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 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 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. This workflow ensures that code changes and documentation updates remain paired in the same commit history.

Tool-Generation Input

The scripts/make-docs.sh script ingests 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 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:

container run -it ubuntu:latest /bin/bash

(Documented under "container run", lines 12–20)

Build an image with a custom Dockerfile and multiple tags:

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:

container list --format json --all

(Documented under "container list (ls)", lines 36–44)

Create a new container machine and set it as the default:

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 — The central Markdown document listing every CLI command, flag, and example.
• 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 — 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 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 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 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 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 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.

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