[Request]: Clean up help for complex commands.

[jglogan]

Feature or enhancement request details

Help output for commands is a bit hectic. We should go through each command and make sure that help output is well organized and easy to scan and understand.

We also need a way to document complex option values (e.g. --publish) without cluttering things.

Worst-case example:

% 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

OPTIONS:
  -w, --cwd, --workdir <cwd>
                          Current working directory for the container
  -e, --env <env>         Set environment variables
  --env-file <env-file>   Read in a file of environment variables
  --uid <uid>             Set the uid for the process
  --gid <gid>             Set the gid for the process
  -i, --interactive       Keep Stdin open even if not attached
  -t, --tty               Open a tty with the process
  -u, --user <user>       Set the user for the process
  -c, --cpus <cpus>       Number of CPUs to allocate to the container
  -m, --memory <memory>   Amount of memory in bytes, kilobytes (K), megabytes (M), or gigabytes (G) for the container, with MB granularity (for example, 1024K will result in 1MB being allocated
                          for the container)
  -d, --detach            Run the container and detach from the process
  --entrypoint <entrypoint>
                          Override the entrypoint of the image
  --mount <mount>         Add a mount to the container (type=<>,source=<>,target=<>,readonly)
  -p, --publish <publish> Publish a port from container to host (format: [host-ip:]host-port:container-port[/protocol])
  --publish-socket <publish-socket>
                          Publish a socket from container to host (format: host_path:container_path)
  --tmpfs <tmpfs>         Add a tmpfs mount to the container at the given path
  --name <name>           Assign a name to the container. If excluded will be a generated UUID
  --remove, --rm          Remove the container after it stops
  --os <os>               Set OS if image can target multiple operating systems (default: linux)
  -a, --arch <arch>       Set arch if image can target multiple architectures (default: arm64)
  -v, --volume <volume>   Bind mount a volume into the container
  -k, --kernel <kernel>   Set a custom kernel path
  --network <network>     Attach the container to a network
  --cidfile <cidfile>     Write the container ID to the path provided
  --no-dns                Do not configure DNS in the container
  --dns <dns>             DNS nameserver IP address
  --dns-domain <dns-domain>
                          Default DNS domain
  --dns-search <dns-search>
                          DNS search domains
  --dns-option <dns-option>
                          DNS options
  -l, --label <label>     Add a key=value label to the container
  --virtualization        Expose virtualization capabilities to the container. (Host must have nested virtualization support, and guest kernel must have virtualization capabilities enabled)
  --ssh                   Forward SSH agent socket to container
  --scheme <scheme>       Scheme to use when connecting to the container registry. One of (http, https, auto) (default: auto)
  --debug                 Enable debug output [environment: CONTAINER_DEBUG]
  --disable-progress-updates
                          Disable progress bar updates
  --version               Show the version.
  -h, --help              Show help information.

Code of Conduct

• I agree to follow this project's Code of Conduct

[timsneath]

It's worth thinking about whether we can divide this into "basic" and "advanced" commands and hide the latter behind a verbose flag. I worry that a new user will be overwhelmed with options. Is it common to assign a custom tmpfs mount point or to manually set uid/gid for the process, for instance?

Another idea is to include a sample command that shows a basic invocation, e.g. container run foo -it sh.