How to RTFM well to get a CLI command

The pager

less(1)

less(1) is the usual pager nowadays; you would do well learning to use it. It's also used for paging the manual pages, in most systems. The most common operation is searching, which is done by pressing /. Press h within the pager, or run less --help to read its help for interactive use of the pager.

While reading a manual page, I often find myself searching for specific options of a command. Imagine I want to search for the option -type of find(1). I type /^ *-type (or being lazy, I often type / -type --at least three spaces between / and -; this forum collapses multiple spaces--).

Filtering

grep(1)

It may be useful to produce an index of a manual page:

$ man ldd | grep -e '^ \{0,3\}[^ ]' -e '^ \{4,7\}-'
ldd(1)                      General Commands Manual                     ldd(1)
NAME
SYNOPSIS
DESCRIPTION
   Security
OPTIONS
     --version
     --verbose
     -v     Print  all  information, including, for example, symbol versioning
     --unused
     -u     Print unused direct dependencies.  (Since glibc 2.3.4.)
     --data-relocs
     -d     Perform relocations and report any missing objects (ELF only).
     --function-relocs
     -r     Perform relocations for both data objects and functions,  and  re‐
     --help
BUGS
SEE ALSO
Linux man‐pages (unreleased)        (date)                              ldd(1)

You can use more complex filters to, for example, read only a specific section(s) of a manual page.

whatis(1) vs apropos(1)

Both programs display the name of some pages, followed by a short description of them (it is the NAME (or Name) section of the manual page that these commands print). They differ in what they find.

whatis(1)

You ask what is a term (a command, a C function, ...), and it tells you a short description.

This program searches for manual pages whose name matches the term you specified.

apropos(1)

This program searches both the name of pages and their short description for the term you specified. It's more like "I'm not sure what I'm searching for, please show me anything that resembles this".

Other documentation formats

info(1)

info(1) is an alternative system, much more complex than man(1). The GNU project doesn't like manual pages, and developed their own documentation format, and formatter. GNU programs always have info(1) documentation, and often (but not always) they also have manual pages. Non-GNU projects tend to only have manual pages.

I read their manual pages, unless I don't find what I'm looking for, in which case I look at their info(1) manual.

If you find info(1) difficult to use, you can pipe it to less(1) to read it all in one take, as if it were a manual page:

info printf | less

help(1)

Shells usually provide a help(1) command that documents the built-ins of the shell. This is the case with read, cd, ... There's no binary program being run, but rather a built-in function within the shell; this can optimize some common operations, or in some cases it's impossible to implement some functionality in the form of a binary program (e.g., cd).

Most of these built-ins are defined by POSIX, so you can still read the POSIX manual page for the utility (install manpages-posix on Debian).

tldr(1)

These pages present short and common examples with a short explanation. Sometimes it's easier to start reading examples rather than trying to read a descriptive page. On Debian, apt-get install tldr; then, for example, use tldr tar to read examples of use of tar(1).

https://tldr.sh/

Interactive programs

In interactive programs, there's usually a key that shows the help of the program, reminding you the keys for the interactive commands of the program. less(1) uses h; mutt(1) uses ?. h and ? are common keys for that.

posted 6 months ago

CC BY-SA 4.0

6mo ago

alx‭

259 reputation 8 13 32 102

The existing answer is good, but I'll add a short version.

1. man FOO is the most reliable way. A large majority of programs have a man page, and a large majority of man pages cover all aspects of the program (assuming you have the patience to read it).
   • By default, most Linuxes will open the man page in less.
   • There are ways to colorize man pages to make them more readable. This should be a separate question.
   • A useful trick is to pipe into grep: man ls | grep -C 3 date
   • See also: https://linux.codidact.com/posts/289489
2. tldr FOO is a much shorter, third party, community managed summary of how to use a command. There are even more commands without a tldr page than without a man page, however most things have a tldr page. There are some competitors like bropages, cheat pages, etc. but usually tldr has the superset of information.
3. Installing a good shell completion tool is very helpful. For example, fish shell by default can tab-complete many commands, with not just a list of possible arguments but also their descriptions. Other shells have plugins with similar functions.
4. It is common courtesy for CLI programs to support either a -h or --help argument. You can pipe this into grep as well if long.
5. These days it is useful to search online for a program's git repo, and read the readme and/or repo wiki since developers like to start documenting there.
6. The Arch wiki and Gentoo wiki are currently great go-to resources for individual programs. They don't have all programs but they have most. If you are not using Arch/Gentoo you may need to adapt some instructions.

posted 4 months ago

CC BY-SA 4.0

matthewsnyder‭

1086 reputation 79 53 175 73