Cleans up option groups, container subcommand help. #647

jglogan · 2025-09-19T06:06:45Z

Part of [Request]: Clean up help for complex commands. #515.
Add titles to option groups for container subcommands.
Order option groups and container subcommand options alphabetically.
Use container-id and container-ids consistently as argument names.
Shorten long valueNames to avoid option column overflow in help output where possible.
Replace customShort and customLong with short, long, and shortAndLong where possible.
Always place global options and arguments after alphabetized command-specific options.
Rename RunCommand to ContainerRun and relocate it.
Rename Executable to ContainerCLI.

Type of Change

Bug fix
New feature
Breaking change (if you're depending on RunCommand, renamed).
Documentation update

Motivation and Context

See #385.

Testing

Tested locally
Added/updated tests
Added/updated docs

jglogan · 2025-09-19T06:07:36Z

% container run --help                     
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Run a container

USAGE: container run [<options>] <image> [<arguments> ...]

ARGUMENTS:
  <image>                 Image name
  <arguments>             Container init process arguments

PROCESS OPTIONS:
  -e, --env <env>         Set environment variables (format: key=value)
  --env-file <env-file>   Read in a file of environment variables (key=value format, ignores # comments and blank lines)
  --gid <gid>             Set the group ID for the process
  -i, --interactive       Keep the standard input open even if not attached
  -t, --tty               Open a TTY with the process
  -u, --user <user>       Set the user for the process (format: name|uid[:gid])
  --uid <uid>             Set the user ID for the process
  -w, --workdir, --cwd <dir>
                          Set the initial working directory inside the container

RESOURCE OPTIONS:
  -c, --cpus <cpus>       Number of CPUs to allocate to the container
  -m, --memory <memory>   Amount of memory (1MByte granularity), with optional K, M, G, T, or P suffix

MANAGEMENT OPTIONS:
  -a, --arch <arch>       Set arch if image can target multiple architectures (default: arm64)
  --cidfile <cidfile>     Write the container ID to the path provided
  -d, --detach            Run the container and detach from the process
  --dns <ip>              DNS nameserver IP address
  --dns-domain <domain>   Default DNS domain
  --dns-option <option>   DNS options
  --dns-search <domain>   DNS search domains
  --entrypoint <cmd>      Override the entrypoint of the image
  -k, --kernel <path>     Set a custom kernel path
  -l, --label <label>     Add a key=value label to the container
  --mount <mount>         Add a mount to the container (format: type=<>,source=<>,target=<>,readonly)
  --name <name>           Use the specified name as the container ID
  --network <network>     Attach the container to a network
  --no-dns                Do not configure DNS in the container
  --os <os>               Set OS if image can target multiple operating systems (default: linux)
  -p, --publish <spec>    Publish a port from container to host (format: [host-ip:]host-port:container-port[/protocol])
  --platform <platform>   Platform for the image if it's multi-platform. This takes precedence over --os and --arch
  --publish-socket <spec> Publish a socket from container to host (format: host_path:container_path)
  --rm, --remove          Remove the container after it stops
  --ssh                   Forward SSH agent socket to container
  --tmpfs <tmpfs>         Add a tmpfs mount to the container at the given path
  -v, --volume <volume>   Bind mount a volume into the container
  --virtualization        Expose virtualization capabilities to the container (requires host and guest support)

REGISTRY OPTIONS:
  --scheme <scheme>       Scheme to use when connecting to the container registry. One of (http, https, auto) (default: auto)

PROGRESS OPTIONS:
  --disable-progress-updates
                          Disable progress bar updates

OPTIONS:
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

% container create --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Create a new container

USAGE: container create [<options>] <image> [<arguments> ...]

ARGUMENTS:
  <image>                 Image name
  <arguments>             Container init process arguments

PROCESS OPTIONS:
  -e, --env <env>         Set environment variables (format: key=value)
  --env-file <env-file>   Read in a file of environment variables (key=value format, ignores # comments and blank lines)
  --gid <gid>             Set the group ID for the process
  -i, --interactive       Keep the standard input open even if not attached
  -t, --tty               Open a TTY with the process
  -u, --user <user>       Set the user for the process (format: name|uid[:gid])
  --uid <uid>             Set the user ID for the process
  -w, --workdir, --cwd <dir>
                          Set the initial working directory inside the container

RESOURCE OPTIONS:
  -c, --cpus <cpus>       Number of CPUs to allocate to the container
  -m, --memory <memory>   Amount of memory (1MByte granularity), with optional K, M, G, T, or P suffix

MANAGEMENT OPTIONS:
  -a, --arch <arch>       Set arch if image can target multiple architectures (default: arm64)
  --cidfile <cidfile>     Write the container ID to the path provided
  -d, --detach            Run the container and detach from the process
  --dns <ip>              DNS nameserver IP address
  --dns-domain <domain>   Default DNS domain
  --dns-option <option>   DNS options
  --dns-search <domain>   DNS search domains
  --entrypoint <cmd>      Override the entrypoint of the image
  -k, --kernel <path>     Set a custom kernel path
  -l, --label <label>     Add a key=value label to the container
  --mount <mount>         Add a mount to the container (format: type=<>,source=<>,target=<>,readonly)
  --name <name>           Use the specified name as the container ID
  --network <network>     Attach the container to a network
  --no-dns                Do not configure DNS in the container
  --os <os>               Set OS if image can target multiple operating systems (default: linux)
  -p, --publish <spec>    Publish a port from container to host (format: [host-ip:]host-port:container-port[/protocol])
  --platform <platform>   Platform for the image if it's multi-platform. This takes precedence over --os and --arch
  --publish-socket <spec> Publish a socket from container to host (format: host_path:container_path)
  --rm, --remove          Remove the container after it stops
  --ssh                   Forward SSH agent socket to container
  --tmpfs <tmpfs>         Add a tmpfs mount to the container at the given path
  -v, --volume <volume>   Bind mount a volume into the container
  --virtualization        Expose virtualization capabilities to the container (requires host and guest support)

REGISTRY OPTIONS:
  --scheme <scheme>       Scheme to use when connecting to the container registry. One of (http, https, auto) (default: auto)

OPTIONS:
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:09:17Z

% container build --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Build an image from a Dockerfile

USAGE: container build [<options>] [<context-dir>]

ARGUMENTS:
  <context-dir>           Build directory (default: .)

OPTIONS:
  -a, --arch <value>      Add the architecture type to the build
  --build-arg <key=val>   Set build-time variables
  -c, --cpus <cpus>       Number of CPUs to allocate to the builder container (default: 2)
  -f, --file <path>       Path to Dockerfile (default: Dockerfile)
  -l, --label <key=val>   Set a label
  -m, --memory <memory>   Amount of builder container memory (1MByte granularity), with optional K, M, G, T, or P suffix (default: 2048MB)
  --no-cache              Do not use cache
  -o, --output <value>    Output configuration for the build (format: type=<oci|tar|local>[,dest=]) (default: type=oci)
  --os <value>            Add the OS type to the build
  --platform <platform>   Add the platform to the build (takes precedence over --os and --arch)
  --progress <type>       Progress type (format: auto|plain|tty)] (default: auto)
  -q, --quiet             Suppress build output
  -t, --tag <name>        Name for the built image (default: c6bf6da3-eced-4378-b048-48e27933fb1e)
  --target <stage>        Set the target build stage
  --vsock-port <port>     Builder-shim vsock port (default: 8088)
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:09:50Z

% container delete --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Delete one or more containers

USAGE: container delete [--all] [--force] [--debug] [<container-ids> ...]

ARGUMENTS:
  <container-ids>         Container IDs

OPTIONS:
  -a, --all               Remove all containers
  -f, --force             Force the removal of one or more running containers
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:10:19Z

% container exec --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Run a new command in a running container

USAGE: container exec [--env <env> ...] [--env-file <env-file> ...] [--gid <gid>] [--interactive] [--tty] [--user <user>] [--uid <uid>] [--workdir <dir>] [--debug] <container-id> <arguments> ...

ARGUMENTS:
  <container-id>          Container ID
  <arguments>             New process arguments

PROCESS FLAGS:
  -e, --env <env>         Set environment variables (format: key=value)
  --env-file <env-file>   Read in a file of environment variables (key=value format, ignores # comments and blank lines)
  --gid <gid>             Set the group ID for the process
  -i, --interactive       Keep the standard input open even if not attached
  -t, --tty               Open a TTY with the process
  -u, --user <user>       Set the user for the process (format: name|uid[:gid])
  --uid <uid>             Set the user ID for the process
  -w, --workdir, --cwd <dir>
                          Set the initial working directory inside the container

OPTIONS:
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:10:42Z

 % container inspect --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Display information about one or more containers

USAGE: container inspect [--debug] <container-ids> ...

ARGUMENTS:
  <container-ids>         Container IDs

OPTIONS:
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:11:01Z

% container kill --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Kill or signal one or more running containers

USAGE: container kill [--all] [--signal <signal>] [--debug] [<container-ids> ...]

ARGUMENTS:
  <container-ids>         Container IDs

OPTIONS:
  -a, --all               Kill or signal all running containers
  -s, --signal <signal>   Signal to send to the container(s) (default: KILL)
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:11:26Z

% container list --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: List containers

USAGE: container list [--all] [--format <format>] [--quiet] [--debug]

OPTIONS:
  -a, --all               Show stopped containers as well
  --format <format>       Format of the output (values: json, table; default: table)
  -q, --quiet             Only output the container ID
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:11:46Z

% container logs --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Fetch container logs

USAGE: container logs [--boot] [--follow] [-n <n>] [--debug] <container-id>

ARGUMENTS:
  <container-id>          Container ID

OPTIONS:
  --boot                  Display the boot log for the container instead of stdio
  -f, --follow            Follow log output
  -n <n>                  Number of lines to show from the end of the logs. If not provided this will print all of the logs
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:12:18Z

% container start --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Start a container

USAGE: container start [--attach] [--interactive] [--debug] <container-id>

ARGUMENTS:
  <container-id>          Container ID

OPTIONS:
  -a, --attach            Attach STDOUT/STDERR
  -i, --interactive       Attach STDIN
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

jglogan · 2025-09-19T06:12:58Z

% container stop --help
Warning! Running debug build. Performance may be degraded.
OVERVIEW: Stop one or more running containers

USAGE: container stop [--all] [--signal <signal>] [--time <time>] [--debug] [<container-ids> ...]

ARGUMENTS:
  <container-ids>         Container IDs

OPTIONS:
  -a, --all               Stop all running containers
  -s, --signal <signal>   Signal to send the containers (default: SIGTERM)
  -t, --time <time>       Seconds to wait before killing the containers (default: 5)
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --version               Show the version.
  -h, --help              Show help information.

dkovba

👍 Comments apply to all help strings with the same value.

Sources/ContainerClient/Flags.swift

Sources/ContainerCommands/BuildCommand.swift

Sources/ContainerClient/Flags.swift

- Part of apple#515. - Add titles to option groups for container subcommands. - Order option groups and container subcommand options alphabetically. - Shorten long valueNames to avoid option column overflow in help output where possible. - Replace customShort and customLong with short, long, and shortAndLong where possible. - Always place global options and arguments after alphabetized command-specific options. - Rename RunCommand to ContainerRun and relocate it. - Rename Executable to ContainerCLI. - Update command reference doc.

dkovba approved these changes Sep 20, 2025

View reviewed changes

jglogan force-pushed the option-groups branch 6 times, most recently from 197dae5 to 9ee1cec Compare September 22, 2025 19:58

jglogan force-pushed the option-groups branch from 9ee1cec to 89f73da Compare September 22, 2025 22:38

jglogan requested a review from dkovba September 22, 2025 22:38

PR feedback - inconsistent option group description.

6b3ac28

dkovba approved these changes Sep 22, 2025

View reviewed changes

jglogan merged commit f3b33ff into apple:main Sep 22, 2025
2 checks passed

jglogan deleted the option-groups branch September 22, 2025 23:36

jglogan mentioned this pull request Sep 23, 2025

[Request]: Clean up help for complex commands. #515

Closed

1 task

Cleans up option groups, container subcommand help. #647

Cleans up option groups, container subcommand help. #647

Uh oh!

Conversation

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Motivation and Context

Testing

Uh oh!

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Sep 19, 2025

Uh oh!

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Sep 19, 2025

Uh oh!

jglogan commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dkovba left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jglogan commented Sep 19, 2025 •

edited

Loading

jglogan commented Sep 19, 2025 •

edited

Loading

jglogan commented Sep 19, 2025 •

edited

Loading

jglogan commented Sep 19, 2025 •

edited

Loading

jglogan commented Sep 19, 2025 •

edited

Loading

jglogan commented Sep 19, 2025 •

edited

Loading

jglogan commented Sep 19, 2025 •

edited

Loading

jglogan commented Sep 19, 2025 •

edited

Loading

jglogan commented Sep 19, 2025 •

edited

Loading