Command-line terminology: gcloud command-line tool and Linux

This topic discusses what to call the command-line elements that are used in the gcloud command-line tool and in Linux commands.

General guidance

When discussing commands and their constituent parts, follow this guidance:

  • Avoid mapping nomenclature of the gcloud tool's commands to Linux commands.
  • Linux commands can be complicated. It is 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 Platform–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

Where:

  • 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 a variable called JOB_NAME that was set earlier.
  • --package-path is a flag.

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 details, see the Cloud SDK: gcloud topic.

Linux commands

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. Here's an example:

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

Where:

  • 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.

A word of caution: Linux command syntax is notoriously complex. This topic covers only the most common elements. For a more detailed reference, see The Linux Command Line

Send feedback about...

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide