--help structure

Web CLI Guidelines
1

$ program help
Usage:
program [OPTION]…

Summary:
Program is a program that does wonders!

Commands can be grouped | classified as follows:
Metasyntactic variables: foo, bar, baz
Category: foo1, bar1

For more information on a command program help <command>.
For more help [go here (URL of docs)].

Example:
$ snap help
Usage:
snap […]

Summary:
The snap command lets you install, configure, refresh and remove snaps.
Snaps are packages that work across many different Linux distributions,
enabling secure delivery and operation of the latest apps and utilities.

Commands can be classified as follows:

     Basics: find, info, install, list, remove
    ...more: refresh, revert, switch, disable, enable
    History: changes, tasks, abort, watch
    Daemons: services, start, stop, restart, logs
   Commands: alias, aliases, unalias, prefer

Configuration: get, set, unset, wait
Account: login, logout, whoami
Permissions: connections, interface, connect, disconnect
Snapshots: saved, save, check-snapshot, restore, forget
Other: version, warnings, okay, ack, known, model, create-cohort, recovery
Development: run, pack, try, download, prepare-image

For more information about a command, run 'snap help '.
For a short summary of all commands, run ‘snap help --all’.

2

Maybe mention that usage for mandatory arguments mentions use of angled brackets
(from https://en.wikipedia.org/wiki/Usage_message)

On Unix-like platforms, usage messages usually follow the same common pattern:

  • They often begin with “Usage:” , the command, followed by a list of arguments.
  • To indicate optional arguments, Square brackets are commonly used, and can also be used to group parameters that must be specified together.
  • To indicate required arguments, Angled brackets are commonly used, following the same grouping conventions as square brackets.
  • Exclusive parameters can be indicated by separating them with vertical bars within groups.
1 Like
3

Thanks @sergiusens, we’re going to iterate on this including your suggestions.