gcloud alpha topic command-conventions

gcloud alpha topic command-conventions - gcloud command conventions supplementary help

Conventions are goals more than rules. Refer to individual command --help for any exceptions.

All groups and commands have a --help flag that displays a man(1) style document on the standard output. The display is run through the default pager if the calling environment specifies one. Help documents are derived from the running executable, so they are always up to date, even when switching between multiple release installations.

gcloud GROUP GROUP … COMMAND POSITIONAL … FLAG …

Flag and positional arguments can be intermixed but for consistency are usually displayed positionals first in order, followed by flags in any order.

gcloud foo bar NAME [EXTRA] [--format=FORMAT]

is the usage for the gcloud foo bar command with a required NAME positional argument, an optional EXTRA positional argument, and an optional --format flag argument.

Mutually exclusive arguments are separated by |; at most one arg in the list of mutually exclusive args may be specified:

[ --foo | --bar ]

This means that either --foo or --bar may be specified, but not both.

Mutually exclusive args may also be required, meaning exactly one arg in the list must be specified. This is denoted by enclosing the args in ( … ):

( --foo | --bar )

Modal argument groups are also supported. If any arg in the group is specified, then the modal arguments must also be specified. This is denoted by using : to separate the modal args on the left from the other args on the right:

[ --must-a --must-b : --maybe-c --maybe-d ]

This means that if --maybe-c and/or --maybe-d are specified then both --must-a and --must-b must be specified.

File input arguments usually accept the special name - to mean read from the standard input. This can be used only once per command line.

Following UNIX convention, if a flag is repeated on the command line, then only the rightmost occurrence takes effect, no diagnostic is emitted. This makes it easy to set up command aliases and wrapper scripts that provide default flag values; values that can easily be overridden by specifying them on the alias or wrapper script command line.

--flag=value

or by placing the value as the next arg after the flag:

--flag value

The = form must be used if value starts with -.

The second form requires extra context to determine if --flag is Boolean and value is a positional, or if --flag is valued and value is its value. Because of the visual ambiguity, usage notation and most command examples use the first form to make intentions clear. The = form also has a diagnostic bonus: it is an error to specify a value for a Boolean flag.

Depending on the context, there may be guarantees on the output format to support deterministic parsing. Certain commands do return resources and these resources are listed on standard output usually using either a command-specific table format or the default YAML format. Moreover, the --format flag can be used to change or configure these default output formats. yaml, json, and csv output --format values guarantee that successful command completion results in standard output data that can be parsed using the respective format. A detailed explanation of the capabilities of the --format flag can be found with $ gcloud topic formats. In the case of async commands, or commands run with --async, the resource returned on standard output is an operations resource. For commands that do not return resources, the output is defined in the command's --help.

The standard error is reserved for diagnostics. In general, the format of standard error data may change from release to release. Users should not script against specific content, or even the existence of output to the standard error at all. The only reliable error indicator is the exit status described below.

Most standard error messaging is also logged to a file that can be accessed by $ gcloud info --show-log.

No gcloud command should crash with an uncaught exception. However, if gcloud does crash the stack trace is intercepted and written to the log file, and a crash diagnostic is written to the standard error.

Any other exit status indicates an error. Command-specific diagnostics should explain the nature of the error and how to correct it.