Skip to content

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

@jglogan

Description

@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

Metadata

Metadata

Assignees

Labels

nextItems in scope for the next few milestonesuxUser experience features and fixes.

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions