Using Commands Built-in Help

Using Commands' Built-in Help

The most common way to learn about a command is to read its built-in help. Many commands support an option that displays information about the command, and almost all commands display a usage message (saying how they are best used) if they are invoked with improper arguments or options.

Built-in help is terse, often consisting only of a usage message using the format shown in Figure 3.2. Still, it is easily available and often reminds you of the available options and required arguments.

There isn't a consistent way to get built-in help from commands, but there are several ways that work.

To see the built-in help from a command:

• Try invoking the command with the --help option (that's two hyphens).
  
  For example, try
  
  softwareupdate --help
  
  Some commands (like softwareupdate ) provide an extensive listing of available options (see Figure 3.4 for a partial listing from the ssh command).
  
  

  Figure 3.4. Some commands (like softwareupdate ) give an extensive listing of available options; this is the result when you type softwareupdate --help .

   user-vc8f9gd:~ vanilla$  softwareupdate --help  usage: softwareupdate <mode> [<args> ...]        -l  --list             List all appropriate updates        -d  --download         Download Only        -i  --install          Install                  <label> ...   specific updates                  -a  --all              all appropriate updates                  -r  --recommended      only recommended updates                  -u  --url <url> ...    from signed package URLs        Per-user preferences:        --ignore <label> ...         Ignore specific updates        --reset-ignored               Clear all ignored updates        --schedule (on  off)         Set automatic checking        -h  --help         Print this help user-vc8f9gd:~ vanilla$ 

  
  For some commands, the --help option is not valid, and for others it looks like a valid option but doesn't provide any help.
  
  
• In some cases, using a single hyphen gives something useful:
  
  ssh -help
  
  Even though -help is not a valid option to the ssh command, it still gives you some insight. Most commands give a "usage" message when invoked with an invalid option or without a required argument. Figure 3.5 shows the output from ssh when invoked with the -help option.
  
  

  Figure 3.5. What you get when you type ssh -help .

   user-vc8f9gd:~ vanilla$ ssh -help ssh: illegal option  h usage: ssh  [-1246AaCfghkNnqsTtVvXxY] [-b bind_address] [-c cipher_spec]             [-D port] [-e escape_char] [-F configfile] [-i identity_file]             [-L port:host:hostport] [-l login_name] [-m mac_spec] [-o option]             [-p port] [-R port:host:hostport] [user@]hostname [command] user-vc8f9gd:~ vanilla$ 

  
  
• In some cases the -h option will produce a help message.
  
  The man command is an example of a command that will give you a help message if you invoke it with the -h option:
  
  man -h
  
  

Tips

• Try deliberately using an invalid option, such as -XXX , and see what happens.

• If the built-in help is not helpful or is missing, just refer to the man page.