.TH "GCLOUD_ALPHA_TOPIC_FORMATS" 1



.SH "NAME"
.HP
gcloud alpha topic formats \- resource formats supplementary help



.SH "DESCRIPTION"

\fB(ALPHA)\fR Most \fBgcloud\fR commands return a list of resources on success.
By default they are pretty\-printed on the standard output. The
\fB\-\-format=\fR\fINAME\fR[\fIATTRIBUTES\fR]\fB(\fR\fIPROJECTION\fR\fB)\fR and
\fB\-\-filter=\fR\fIEXPRESSION\fR flags along with projections can be used to
format and change the default output to a more meaningful result.

Use the \f5\-\-format\fR flag to change the default output format of a command.
Resource formats are described in detail below.

Use the \f5\-\-filter\fR flag to select resources to be listed. For details run
$ gcloud topic filters.

Use resource\-keys to reach resource items through a unique path of names from
the root. For details run $ gcloud topic resource\-keys.

Use projections to list a subset of resource keys in a resource. For details run
$ gcloud topic projections.

Note: To refer to a list of fields you can sort, filter, and format by for each
resource, you can run a list command with the format set to \f5text\fR or
\f5json\fR. For example, $ gcloud compute instances list \-\-limit=1
\-\-format=text.

To work through an interactive tutorial about using the filter and format flags
instead, see:
https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/cloud\-shell\-tutorials&page=editor&tutorial=cloudsdk/tutorial.md



.SH "Formats"

A format expression is used to change the default output format of a command.
Many output formats are available; some for pretty printing human\-readable
output and others for returning machine\-readable output.

A format expression has 3 parts:

.RS 2m
.TP 2m
\fINAME\fR
\fIname\fR
.TP 2m
\fIATTRIBUTES\fR
\fB[\fR [no\-]\fIattribute\-name\fR[=\fIvalue\fR] [, ... ] \fB]\fR
.TP 2m
\fIPROJECTION\fR
\fB(\fR \fIresource\-key\fR [, ...] \fB)\fR


.RE
.sp
\fINAME\fR is required, \fIATTRIBUTES\fR are optional, and \fIPROJECTIONS\fR may
be required for some formats. Unknown attribute names are silently ignored.

Each \fBgcloud\fR \fBlist\fR command has a default format expression. The
\fB\-\-format\fR flag can alter or replace the default. For example,

.RS 2m
\-\-format="[box]"
.RE

adds box decorations to a default table, and

.RS 2m
\-\-format=json
.RE

lists the resource in \fBjson\fR format.

The formats and format specific attributes are:

.RS 2m
.TP 2m
\fBconfig\fR
A dictionary of dictionaries in config style.

The format attributes are:

.RS 2m
.TP 2m
\fBexport\fR
Display the dictionary as a list of system specific environment export commands.
.TP 2m
\fBunset\fR
Display the dictionary as a list of system specific environment unset commands.
.RE
.sp

.TP 2m
\fBcsv\fR
Comma Separated Values (http://www.rfc\-editor.org/rfc/rfc4180.txt) with no
keys. This format requires a projection to define the values to be printed.

To use \fB\en\fR or \fB\et\fR as an attribute value please escape the \fB\e\fR
with your shell's escape sequence, example \fBseparator="\e\en"\fR for bash.

The format attributes are:

.RS 2m
.TP 2m
\fBdelimiter="string"\fR
The string printed between list value items, default ";".
.TP 2m
\fBno\-heading\fR
Disables the initial key name heading record.
.TP 2m
\fBseparator="string"\fR
The string printed between values, default ",".
.TP 2m
\fBterminator="string"\fR
The string printed after each record, default "\en" (newline).
.RE
.sp

.TP 2m
\fBdefault\fR
An alias for the \fByaml\fR format. To override use \fBgcloud config set
core/default_format\fR property.

.TP 2m
\fBdiff\fR
A unified diff of the first two projection columns.

The format attributes are:

.RS 2m
.TP 2m
\fBformat\fR
The format of the diffed resources. Each resource is converted to this format
and the diff of the converted resources is displayed. The default is
\'flattened'.
.RE
.sp

.TP 2m
\fBdisable\fR
Disables formatted output and does not consume the resources. Equivalent to the
\fBnone\fR format, but also short\-circuits early for commands that return
pageable lists.

.TP 2m
\fBflattened\fR
A flattened tree. Each output line contains one \fBkey\fR:\fBvalue\fR pair.

The format attributes are:

.RS 2m
.TP 2m
\fBno\-pad\fR
Don't print space after the separator. The default adjusts the space to align
the values into the same output column. Use \fBno\-pad\fR for comparing resource
outputs.
.TP 2m
\fBseparator=\fISEPARATOR\fR\fR
Print \fISEPARATOR\fR between the \fBkey\fR and \fBvalue\fR. The default is ":
".
.RE
.sp

.TP 2m
\fBget\fR
Equivalent to the \fBvalue[no\-transforms]\fR format. Default transforms are not
applied to the displayed values.

.TP 2m
\fBjson\fR
JSON (http://www.json.org), JavaScript Object Notation.

The format attributes are:

.RS 2m
.TP 2m
\fBno\-undefined\fR
Does not display resource data items with null values.
.RE
.sp

.TP 2m
\fBlist\fR
An ordered list of items.

The format attributes are:

.RS 2m
.TP 2m
\fBalways\-display\-title\fR
Display the title even if there are no records.
.TP 2m
\fBcompact\fR
Display all items in a record on one line.
.RE
.sp

.TP 2m
\fBmulti\fR
Each projection key must have a subformat defined by the :format=FORMAT\-STRING
attribute. For example,

.RS 2m
`\-\-format="multi(data:format=json, info:format='table[box](a, b, c)')"`
.RE

formats the \fBdata\fR field as JSON and the \fBinfo\fR field as a boxed table.

The format attributes are:

.RS 2m
.TP 2m
\fBseparator\fR
Separator string to print between each format. If multiple resources are
provided, the separator is also printed between each resource.
.RE
.sp

.TP 2m
\fBnone\fR
Disables formatted output and consumes the resources.

.TP 2m
\fBobject\fR
Bypasses JSON\-serialization and prints the object representation of each
resource.

The format attributes are:

.RS 2m
.TP 2m
\fBseparator\fR
The line printed between resources.
.TP 2m
\fBterminator\fR
The line printed after each resource.
.RE
.sp

.TP 2m
\fBtable\fR
Aligned left\-adjusted columns with optional title, column headings and sorting.
This format requires a projection to define the table columns. The default
column headings are the disambiguated right hand components of the column keys
in ANGRY_SNAKE_CASE. For example, the projection keys (first.name, last.name)
produce the default column heading ('NAME', 'LAST_NAME').

If \fB\-\-page\-size\fR=\fIN\fR is specified then output is grouped into tables
with at most \fIN\fR rows. Headings, alignment and sorting are done per\-page.
The title, if any, is printed before the first table.

If screen reader option is True, you may observe flattened list output instead
of a table with columns. Please refer to $ gcloud topic accessibility to turn it
off.

The format attributes are:

.RS 2m
.TP 2m
\fBall\-box\fR
Prints a box around the entire table and each cell, including the title if any.
.TP 2m
\fBbox\fR
Prints a box around the entire table and the title cells if any.
.TP 2m
\fBformat=\fIFORMAT\-STRING\fR\fR
Prints the key data indented by 4 spaces using \fIFORMAT\-STRING\fR which can
reference any of the supported formats.
.TP 2m
\fBno\-heading\fR
Disables the column headings.
.TP 2m
\fBmargin=N\fR
Right hand side padding when one or more columns are wrapped.
.TP 2m
\fBpad=N\fR
Sets the column horizontal pad to \fIN\fR spaces. The default is 1 for box, 2
otherwise.
.TP 2m
\fBtitle=\fITITLE\fR\fR
Prints a centered \fITITLE\fR at the top of the table, within the table box if
\fBbox\fR is enabled.
.RE
.sp

.TP 2m
\fBtext\fR
An alias for the \fBflattened\fR format.

.TP 2m
\fBvalue\fR
CSV with no heading and <TAB> separator instead of <COMMA>. Used to retrieve
individual resource values. This format requires a projection to define the
value(s) to be printed.

To use \fB\en\fR or \fB\et\fR as an attribute value please escape the \fB\e\fR
with your shell's escape sequence, example \fBseparator="\e\en"\fR for bash.

The format attributes are:

.RS 2m
.TP 2m
\fBdelimiter="string"\fR
The string printed between list value items, default ";".
.TP 2m
\fBquote\fR
"..." quote values that contain delimiter, separator or terminator strings.
.TP 2m
\fBseparator="string"\fR
The string printed between values, default "\et" (tab).
.TP 2m
\fBterminator="string"\fR
The string printed after each record, default "\en" (newline).
.RE
.sp

.TP 2m
\fByaml\fR
YAML (http://www.yaml.org), YAML ain't markup language.

The format attributes are:

.RS 2m
.TP 2m
\fBnull="string"\fR
Display string instead of \f5null\fR for null/None values.
.TP 2m
\fBno\-undefined\fR
Does not display resource data items with null values.
.TP 2m
\fBversion=VERSION\fR
Prints using the specified YAML version, default 1.2.
.RE
.sp
.RE
.sp

All formats have these attributes:

.RS 2m
.TP 2m
\fBdisable\fR
Disables formatted output and does not consume the resources.
.TP 2m
\fBjson\-decode\fR
Decodes string values that are JSON compact encodings of list and dictionary
objects. This may become the default.
.TP 2m
\fBpager\fR
If True, sends output to a pager.
.TP 2m
\fBprivate\fR
Disables log file output. Use this for sensitive resource data that should not
be displayed in log files. Explicit command line IO redirection overrides this
attribute.
.TP 2m
\fBtransforms\fR
Apply projection transforms to the resource values. The default is format
specific; table\-like formats may define default transforms to certain columns.
Use \fBno\-transforms\fR to disable.


.RE
.sp

.SH "EXAMPLES"

List a table of compute instance resources sorted by \fBname\fR with box
decorations and title \fBInstances\fR:

.RS 2m
$ gcloud compute instances list \e
    \-\-format="table[box,title=Instances](name:sort=1, \e
zone:label=zone, status)"
.RE

List a nested table of the quotas of a region:

.RS 2m
$ gcloud compute regions describe us\-central1 \e
    \-\-format="table(quotas:format='table(metric,limit,usage)')"
.RE

Print a flattened list of global quotas in CSV format:

.RS 2m
$ gcloud compute project\-info describe \-\-flatten="quotas[]" \e
    \-\-format="csv(quotas.metric,quotas.limit,quotas.usage)"
.RE

List the disk interfaces for all compute instances as a compact comma separated
list:

.RS 2m
$ gcloud compute instances list \e
    \-\-format="value(disks[].interface.list())"
.RE

List the URIs for all compute instances:

.RS 2m
$ gcloud compute instances list \-\-format="value(uri())"
.RE

List all compute instances with their creation timestamps displayed according to
the local timezone:

.RS 2m
$ gcloud compute instances list \e
    \-\-format="table(name,creationTimestamp.date(tz=LOCAL))"
.RE

List the project authenticated user email address:

.RS 2m
$ gcloud info \-\-format="value(config.account)"
.RE

List resources filtered on repeated fields by projecting subfields on a repeated
message:

.RS 2m
$ gcloud alpha genomics readgroupsets list \e
    \-\-format="default(readGroups[].name)"
.RE

Return the scope of the current instance:

.RS 2m
$ gcloud compute zones list \-\-format="value(selfLink.scope())"
.RE

selfLink is a fully qualified name. (e.g.
\'https://www.googleapis.com/compute/v1/projects/my\-project/zones/us\-central1\-a')
The previous example returns a list of just the names of each zone (e.g.
\'us\-central1\-a'). This is because selfLink.scope() grabs the last part of the
URL segment. To extract selfLink starting from /projects and return the scope of
the current instance:

.RS 2m
$ gcloud compute zones list \e
    \-\-format="value(selfLink.scope(projects))"
.RE

List all scopes enabled for a Compute Engine instance and flatten the
multi\-valued resource:

.RS 2m
$ gcloud compute instances list \e
    \-\-format="flattened(name,serviceAccounts[].email,serviceAccounts\e
[].scopes[].basename())"
.RE

Display a multi\-valued resource's service account keys with the corresponding
service account, extracting just the first '/' delimited part with segment(0):

.RS 2m
$ gcloud iam service\-accounts keys list \e
    \-\-iam\-account=svc\-2\-123@test\-minutia\-123.iam.gserviceaccount.com\e
 \-\-project=test\-minutia\-123 \e
    \-\-format="table(name.scope(serviceAccounts).segment(0):label='se\e
rvice Account',name.scope(keys):label='keyID',validAfterTime)"
.RE

The last example returns a table with service account names without their full
paths, keyID and validity.



.SH "NOTES"

This command is currently in alpha and might change without notice. If this
command fails with API permission errors despite specifying the correct project,
you might be trying to access an API with an invitation\-only early access
allowlist. These variants are also available:

.RS 2m
$ gcloud topic formats
.RE

.RS 2m
$ gcloud beta topic formats
.RE