Documenting command-line syntax

Key Point: Recommendations for documenting command-line tools.

This page shows how to document command-line commands and their arguments. For more information about formatting code that appears in text, placeholders, and code samples, see the following links:

• Code in text
• Formatting placeholders
• Code samples

Command prompt

If your command-line instructions show multiple lines of input, then start each line of input with the $ prompt symbol.

Don't show the current directory path before the prompt, even if part of the instruction includes changing directories. However, if the overall context of the command interface changes—such as from the local machine to a remote machine—then add an additional prompt indicator, as appropriate, for the new context.

Examples

Recommended:

Enter the following code into the terminal:

$ adb devices

The output is the following:

List of devices attached
emulator-5554  device
emulator-5556  device

Recommended:

$ adb shell
shell@ $ screencap /sdcard/screen.png
shell@ $ exit
$ adb pull /sdcard/screen.png

When you're showing a one-line command, the command prompt (the $ symbol) is optional. However, if your page includes both multi-line and one-line commands, then we recommend using the command prompt for all of the commands on the page, for consistency.

If your command-line instructions include a combination of input and output lines, we recommend using separate code blocks for input and output.

Example

Recommended:

$ cat ~/.ssh/my-ssh-key.pub

The output is similar to the following:

ssh-rsa KEY_VALUE USERNAME

Required items (commands, arguments, etc.)

Use text without brackets or braces. Depending on the circumstances, this is likely to be in code font.

Examples

Recommended: gcloud compute project-info describe

Recommended: gcloud alpha functions get-logs FUNCTION_NAME

In these examples, all words and arguments are required.

Optional arguments

Use square brackets around an optional argument.

If there's more than one optional argument, enclose each item in its own set of square brackets.

Example

Recommended: gcloud dns GROUP [GLOBAL_FLAG] [FILENAME]

In this example, GROUP is required but GLOBAL_FLAG and FILENAME are optional.

Mutually exclusive arguments

Use braces (also known as curly braces) to indicate that the user must choose one—and only one—of the items inside the braces. Use vertical bars (also known as pipes) to separate the items. There can be more than two mutually exclusive choices, separated from each other by pipes.

Examples

• Recommended: {FILE_1|FILE_2}

  In this example, choose either FILE_1 or FILE_2.

• Recommended:
  {--source=CLOUD_SOURCE --source-url=SOURCE_URL | --bucket=BUCKET [--source=LOCAL_SOURCE]}

  In this example, there are also two options:

  • Left side of pipe: If the source code is deployed from a cloud repository, the following is required:
    --source=CLOUD_SOURCE --source-url=SOURCE_URL
  • Right side of pipe: If the source code is in a local directory:
    • --bucket=BUCKET is required.
    • --source=LOCAL_SOURCE is optional, as specified by the square brackets.

Arguments that can repeat

Use an ellipsis (...) to indicate that the user can specify multiple values for the argument.

Example

Recommended: gcloud dns GROUP [GLOBAL_FLAG ...]

In this example, the user can specify multiple instances of the optional parameter GLOBAL_FLAG.

Output from commands

You don't have to show output for every command. Only add output if it adds value, for example, if the reader needs to copy a value from the output or if they need to verify a value in the output.

If you are showing output, use an introductory phrase to separate the command from the output.

Recommended: The output is similar to the following:

Recommended: The output is the following:

For information about explaining placeholders in output, see Placeholders in output.

Command-line terminology

When discussing commands and their constituent parts in the gcloud command-line tool and in Linux commands, follow this guidance:

• Avoid mapping nomenclature of the gcloud tool's commands to Linux commands.
• Linux commands can be complicated. It's wise to describe what the entire command does rather than what its individual elements are called.
• For Linux commands or commands in the gcloud tool, ask yourself if the reader must know the name of the command-line element or if explaining the command is sufficient.

gcloud commands

gcloud GROUP | COMMAND [--account=ACCOUNT] [--configuration=CONFIGURATION] \
    [--flatten=[KEY,...]][--format=FORMAT] [--help] [--project=PROJECT_ID] \
    [--quiet, -q][--verbosity=VERBOSITY; default="warning"] [--version, -v] \
    [-h] [--log-http][--trace-token=TRACE_TOKEN] [--no-user-output-enabled]

For the sake of accurate classification, the gcloud tool's syntax distinguishes between a command and a command group. In docs, however, command-line contents are generally referred to as commands.

You can use commands (and groups) alone or with one or more flags. A flag is a Google Cloud–specific term for any element other than the command or group name itself. A command or flag might also take an argument, for example, a region value.

Example command:

gcloud init

Example command with a flag:

gcloud init --skip-diagnostics

Example command with multiple elements:

gcloud ml-engine jobs submit training ${JOB_NAME} \
    --package-path=trainer \
    --module-name=trainer.task \
    --staging-bucket=gs://${BUCKET} \
    --job-dir=gs://${BUCKET}/${JOB_NAME} \
    --runtime-version=1.2 \
    --region=us-central1 \
    --config=config/config.yaml \
    -- \
    --data_dir=gs://${BUCKET}/data \
    --output_dir=gs://${BUCKET}/${JOB_NAME} \
    --train_steps=10000

The preceding command consists of the following elements:

• ml-engine is a gcloud command group.
• jobs is an ml-engine command group.
• submit is a jobs command group.
• training is a submit command.
• ${JOB_NAME} is an argument that refers to an environment variable called JOB_NAME that was set earlier.
• --package-path is a flag.
• -- in isolation separates the gcloud arguments that precede it from the user arguments that follow it.

In addition to the term flag, option is often used as a catchall term when you don't want to mire the reader in specialized nomenclature.

For more information, see the Cloud SDK: gcloud topic.

Linux commands

Caution: Linux command syntax is notoriously complex. This section covers only the most common elements. For a more detailed reference, see The Linux Command Line.

Where the gcloud command-line tool uses the catchall terms flag and option, Linux commands use options, parameters, arguments, and a host of specialized syntax elements. The following is an example:

find /usr/src/linux -follow -type f -name '*.[ch]' | xargs grep -iHn pcnet

The preceding command consists of the following elements:

• find is the command name.
• /usr/src/linux is an argument that specifies the path to look in. Easier to refer to as just a path.
• -follow is an option. The - (dash) is part of the option.
• -type is an option with a value of f.
• -name is an option with a value of '*.[ch]', where the asterisk (*) is a metacharacter signifying a wildcard. Metacharacters are used in Linux shell commands for globbing, or filename expansion. In addition to the asterisk, metacharacters include the question mark (?) and caret (^).

The results of the first command are redirected using a pipe (|) to the xargs grep -iHn pcnet command. Other redirection symbols include >, <, >>, and <<. Redirection means capturing output from a file, command, program, script, or even code block within a script and sending it as input to another file, command, program, or script.

Linux signals

Linux signals require vocabulary choices that are generally discouraged elsewhere in documentation. We recommend using the terms discussed here only in the context of process control.

Signal	Description
SIGKILL	Signal sent to kill a specified process, all members of a specified process group, or all processes on the system. SIGKILL cannot be caught, blocked, or ignored. Do not substitute cancel, end, exit, quit, stop, or terminate.
SIGTERM	Signal sent as a request to terminate a process. Although similar to SIGKILL, this signal gives the process a chance to clean up any child processes that might be running. Do not substitute cancel, end, exit, quit, or stop.
SIGQUIT	Signal sent from a keyboard to quit a process. Some processes can catch, block, or ignore a quit signal. Do not substitute cancel, end, exit, quit, or stop.
SIGINT	Signal sent to interrupt a process immediately. The default action of this signal is to terminate a process gracefully. It can be handled, ignored, or caught. It can be sent from a terminal—for example, when a user presses Control+C. Do not substitute suspend, end, exit, pause, or terminate.
SIGPAUSE	Signal that tells a process to pause, or sleep, until any signal is delivered that either terminates the process or invokes a signal-catching function. Do not substitute cancel or interrupt.
SIGSUSPEND	Signal sent to temporarily suspend execution of a process. Used to prevent delivery of a particular signal during the execution of a critical code section. Do not substitute pause or exit.
SIGSTOP	Signal sent to stop execution of a process for later continuation (upon receiving a SIGCONT signal). SIGSTOP cannot be caught, blocked, or ignored. Do not substitute cancel, end, exit, interrupt, quit, or terminate.