gcloud beta 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 aman(1) style document on the standard output. The display is runthrough the default pager if the calling environment specifies one. Helpdocuments are derived from the running executable, so they are always up todate, even when switching between multiple release installations.

gcloudGROUPGROUP …COMMANDPOSITIONAL …FLAG…

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

gcloudfoobarNAME[EXTRA][--format=FORMAT]

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

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

[--foo|--bar]

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

Mutually exclusive args may also berequired, meaningexactly one arg in the list must be specified. This is denoted by enclosing theargs 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 theright:

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

This means that if--maybe-c and/or--maybe-d arespecified then both--must-a and--must-b must bespecified.

File input arguments usually accept the special name- to meanread from the standard input. This can be used only onceper command line.

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

--flag=value

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

--flagvalue

The= form must be used ifvalue startswith-.

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

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

The standard error is reserved for diagnostics. In general, the format ofstandard error data may change from release to release. Users should not scriptagainst specific content, or even the existence of output to the standard errorat all. The only reliable error indicator is theexitstatus described below.

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

Nogcloud command should crashwith an uncaught exception. However, ifgcloud does crash the stack trace isintercepted and written to the log file, and a crash diagnostic is written tothe standard error.

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