2

Some command line interfaces or command line utilities give some comprehensive documentation or help when --help is appended to the name of the command, for example git:

git --help
# shows comprehensive help docs

Some others show only the command and its arguments (that's all), for example grep:

grep --help
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
    [-e pattern] [-f file] [--binary-files=value] [--color=when]
    [--context[=num]] [--directories=action] [--label] [--line-buffered]
    [--null] [pattern] [file ...]

And others give some assistance, but only because --help is not recognised as a legal option, for examples ls:

ls --help
ls: illegal option -- -
usage: ls [-@ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1%] [file ...]

and netstat:

netstat --help
netstat: illegal option -- -
Usage:  netstat [-AaLlnW] [-f address_family | -p protocol]
    netstat [-gilns] [-f address_family]
    netstat -i | -I interface [-w wait] [-abdgRtS]
    netstat -s [-s] [-f address_family | -p protocol] [-w wait]
    netstat -i | -I interface -s [-f address_family | -p protocol]
    netstat -m [-m]
    netstat -r [-Aaln] [-f address_family]
    netstat -rs [-s]

Question

Are there any generally safe way(s) of getting documentation or help with a CLI or utility without having to google (i.e. from within the terminal)? I currently try --help or -h, but other than that I go straight to google, but would like to know if there are other things to (safely) try before going to google.

8
  • 6
    Have you heard of using the man command. For example: man ls or man grep. You can get comprehensive documentation on man by entering man man. Commented Apr 24, 2021 at 7:26
  • @DavidAnderson I've never used it before, but my eyes have been opened! Thank you!
    – stevec
    Commented Apr 24, 2021 at 7:27
  • @DavidAnderson I just tried for all of the examples above (git, grep, ls, netstat) and it works for all of these different CLI's/utilities. I didn't anticipate that it would be that straight forward. Thanks again
    – stevec
    Commented Apr 24, 2021 at 7:29
  • Try using the mouse to highlight the command, then right click on the highlighted text and select Open man page. Commented Apr 24, 2021 at 7:31
  • 1
    The highlighted text can not contain spaces. Commented Apr 24, 2021 at 7:37

3 Answers 3

10

Have you heard of using the man command. For example: man ls or man grep. You can get comprehensive documentation on man by entering man man.

Some of the basic keys used by the man command are the f key to page forward, the b key to page backward and the q key to quit.

Try using the mouse to highlight the command, then right click on the highlighted text and select Open man page. See example below.

Note: The highlighted text can not contain spaces.

Some commands are builtin. This means the command is part on the current shell. If you are using the zsh shell (which is the macOS default shell), then you will need to enter man zshbuiltins for documentation.

7
  • With zsh you can enable the run-help mechanism that will display zsh builtin help.
    – fd0
    Commented Apr 24, 2021 at 13:06
  • @fd0: Is not run-help just an alias for man? Or, is there something more that I am missing? Commented Apr 24, 2021 at 15:44
  • 1
    @DavidAnderson run-help shows documentation for functionality that's built into the shell rather than being provided by a binary (eg export vs ls), see unix.stackexchange.com/a/282649/301421
    – Eric Reed
    Commented Apr 24, 2021 at 16:55
  • Yes, it is like an alias for man, unless you load the function into your current session. In this case run-help will first search for "help" files before attempting to display a manpage.
    – fd0
    Commented Apr 24, 2021 at 18:20
  • For shell built-ins, use help: e.g. help alias, help export etc.
    – alexis
    Commented Apr 24, 2021 at 22:37
1

Also consider using apropos to "search the whatis database for strings" that can help find the right command.

Use the -t option of man to "format the manual page" in a manner that Preview.app can display:

man -t apropos | open -f -a Preview.app

image

1

An analogous action for obtaining a man-page, described in the answer by @David Anderson, above, can be performed with a shell function that leverages the special URL, x-man-page and the open command. This allows viewing man-pages in a Terminal session without taking over the Terminal window from which man was requested. Instead, a new window will be opened to display the man-page contents.

With bash, add this to your ~/.bashrc file; with zsh add the same to ~/.zshrc:

function xmanpage ()
{
    if [ $#   -eq 1 ]; then
        open x-man-page://$1;
    elif [ $# -eq 2 ]; then
        open x-man-page://$1/$2;
    fi
}

If only a name is passed to the function, the man-page for section-1 (user commands) is returned. To select man-pages from another section, specify the section number of the object, followed by the name in interest. For instance, to see the stat command information:

xmanpage stat

And to see the stat system call details from section-2 of the man-pages, do:

xmanpage 2 stat

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .