Skip to content

Command Syntax and Help Documentation

Most command-line mistakes are not caused by forgetting a command name. They happen because the command line was parsed differently than the user expected. cp report final is three words: a command and two arguments. If the real filename is report final, the unquoted version means something else.

This article explains how to read command syntax, how Bash passes arguments to programs, and how to use the help installed on the machine you are administering. The examples assume Ubuntu Server LTS, Bash, and GNU userland tools. The $ prompt in examples is not part of the command.

The Shape of a Command

Documentation often describes commands with this pattern:

command [OPTION]... [ARGUMENT]...

For example:

ls -lh /var/log

The parts are:

  • ls: the command name.
  • -l and -h: options that change behavior.
  • /var/log: an argument, in this case the directory to list.

In documentation, square brackets mean "optional", and ... means "may be repeated". You do not type the brackets or the ellipsis.

Every program decides how to interpret its own options and arguments. Unix conventions are strong, but not universal. -h means "human-readable" for ls -h, but it means something else or nothing at all for other commands.

Short Options, Long Options, and Values

GNU commands commonly support short and long options:

ls -l -h /var/log
ls -lh /var/log
ls --human-readable -l /var/log

For ls, the first two commands are equivalent because short options can be grouped when they do not require their own value. Do not group options blindly for an unfamiliar command.

Long options that take values are often written in one of these forms:

ls --color=auto
sort --key=2 users.txt
sort --key 2 users.txt

Both --key=2 and --key 2 work with GNU sort, but another program might accept only one form. The correct source is that command's documentation.

Reading an "Invalid Option" Error

Typing an option a program does not recognize produces a specific, informative error rather than a silent failure:

ls -z /var/log

ls: invalid option -- 'z'
Try 'ls --help' for more information.

Read this in two parts. ls: invalid option -- 'z' names the program and the exact character that failed to parse. Try 'ls --help' for more information. is the program telling you where to look next; GNU programs print this line consistently, so it is worth acting on literally rather than guessing at the correct flag.

Confirm this failed before any file was touched:

echo "status=$?"

status=2

GNU utilities commonly return 2 for a usage error, distinct from the 1 many of them return for a runtime failure such as a missing file. The distinction matters when a script checks $? to decide whether to retry: a usage error will fail identically on every retry, while a runtime error might succeed once the underlying condition changes.

Bash Processes the Line First

Before an external program starts, Bash has already interpreted quoting, variables, wildcards, and redirections. A useful way to see argument boundaries is printf:

printf '<%s>\n' one "two words" three

Output:

<one>
<two words>
<three>

The program received three arguments. The quotes are not part of the argument; they only told Bash to keep the space inside two words.

Compare single and double quotes:

name='server01'
printf '<%s>\n' "$name"
printf '<%s>\n' '$name'

<server01>
<$name>

Double quotes allow variable expansion while preserving the result as one word. Single quotes keep the characters literal.

Ending Options with --

Filenames can begin with -. Without care, a program may treat such a name as an option.

Use a lab directory:

mkdir -p ~/lab/syntax
cd ~/lab/syntax
touch -- -draft.txt
ls -l -- -draft.txt

The -- marker tells many Unix commands that option parsing is finished. It does not make an operation safe by itself; it only prevents option confusion.

For deletion in this lab, use interactive mode:

rm -i -- -draft.txt

Warning

rm normally does not move files to a desktop Trash folder. Use deletion examples only in a test directory, verify the target first with ls -l -- <path>, and avoid recursive deletion until you understand its scope.

Which Command Will Run?

Bash can resolve a command name to an alias, function, built-in, keyword, or external executable.

type -a cd echo ls
command -V ls

Possible output:

cd is a shell builtin
echo is a shell builtin
ls is aliased to `ls --color=auto'
ls is /usr/bin/ls

Use type when diagnosing shell behavior. which only searches executable files in PATH on many systems, so it can miss aliases, functions, and built-ins.

To see the command search path:

echo "$PATH"

PATH is a colon-separated list of directories searched from left to right. If the current directory is not in PATH, run a trusted executable there with an explicit relative path:

./script.sh

Do not put . at the beginning of PATH on a server. A malicious executable in the current directory could shadow a normal command.

Exit Status and Conditional Execution

Human-readable output is not the same as machine-readable success. Commands return an exit status.

ls -ld /etc
echo "status=$?"

ls -ld /does-not-exist
echo "status=$?"

Typical output:

drwxr-xr-x 160 root root 12288 Jul 29 12:00 /etc
status=0
ls: cannot access '/does-not-exist': No such file or directory
status=2

The general convention is 0 for success and non-zero for another condition. Exact meanings belong to the command.

Use && and || when the next action depends on the previous status:

test -r /etc/hosts && echo "hosts file is readable"
test -r /root/secret || echo "not readable as this user"

The second example is a read-only permission check. Do not add sudo until you know why elevated access is required and whether policy allows it.

Help Layers

A reliable administrator checks the documentation installed on the target system first. That documentation matches the version actually installed.

Built-In Shell Help

Bash built-ins use Bash help:

help cd
help export
help type

This matters because man cd may not describe Bash's cd directly, and there may be no external cd command to document.

--help for Fast Syntax

GNU programs commonly support:

cp --help
ls --help
tail --help

Read the Usage: line first, then scan for the option you need. Remember that --help output is concise; it is not always enough to understand edge cases.

Manual Pages

Use man for local reference documentation:

man ls
man 5 passwd
man 1 passwd

Manual sections matter. man 1 passwd documents the user command. man 5 passwd documents the /etc/passwd file format.

Inside the pager:

  • Space: next page.
  • Enter: one line down.
  • /pattern: search forward.
  • n: next match.
  • N: previous match.
  • g: top.
  • G: bottom.
  • q: quit.

Searching Manual Pages

If you do not know the command name:

apropos "copy files"
man -k "copy files"

These search the manual page database. On a minimal system, the database may be missing or stale. If results look incomplete, an administrator may need to run mandb, usually with sudo, because it updates system-wide indexes. That is a maintenance action, not a learning-lab command.

Info Manuals

GNU projects often provide deeper info documentation:

info coreutils 'ls invocation'

Minimal servers may not have every Info manual installed. Use man and --help when info is unavailable.

Practical Scenario: Checking an Unknown Command Safely

Problem: a teammate sends this command:

install -m 0644 app.conf /etc/myapp/

Do not paste it into production as root. It writes under /etc, may overwrite a file, and changes permissions.

Check the command source:

type -a install

Read the syntax:

install --help
man install

Test in a lab directory first:

mkdir -p ~/lab/syntax/source ~/lab/syntax/dest
printf 'mode=lab\n' > ~/lab/syntax/source/app.conf
install -m 0644 ~/lab/syntax/source/app.conf ~/lab/syntax/dest/
ls -l ~/lab/syntax/dest/app.conf
cat ~/lab/syntax/dest/app.conf

Expected output includes:

-rw-r--r-- ... app.conf
mode=lab

Conclusion: you now know that install can copy a file and set its mode in one step. For the real /etc/myapp/ command, you still need a backup, a config validator, and permission to make the change.

Common Mistakes

  • Typing documentation notation such as [OPTION] literally.
  • Assuming every command uses -h for help.
  • Forgetting that quotes are consumed by the shell and are not passed as characters.
  • Using which as the only diagnostic for command source.
  • Inspecting $? too late, after another command has already replaced it.
  • Running an unknown command with sudo before reading what it writes.

Exercises

  1. Use type -a on cd, pwd, echo, ls, and printf. Explain the result for each.
  2. Create a file named two words.txt in ~/lab/syntax, then prove with printf '<%s>\n' why quoting is required.
  3. Run man 1 passwd and man 5 passwd. Write one sentence describing the difference.
  4. Use apropos archive and choose one command to inspect with both --help and man.

Verification criterion: when given a new command, you should be able to identify what will execute, which arguments it will receive, and where to find its authoritative local documentation.

References

  • Bash manual page: https://man7.org/linux/man-pages/man1/bash.1.html
  • GNU Bash Reference Manual: https://www.gnu.org/software/bash/manual/bash.html
  • GNU Coreutils manual: https://www.gnu.org/software/coreutils/manual/coreutils.html
  • Linux manual pages project: https://man7.org/linux/man-pages/
  • POSIX utility conventions: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap12.html