GCLOUD_TOPIC_FORMATS(1)

NAME

gcloud topic formats - resource formats supplementary help

DESCRIPTION
Most gcloud commands return a list of resources on success. By default they are pretty-printed on the standard output. The --format=NAME[ATTRIBUTES](PROJECTION) flag changes the default output:

    NAME
        The format name.

    ATTRIBUTES
        Format specific attributes. Resource formats are described in detail below.

    PROJECTION
        A list of resource keys that selects the data listed. For details run $ gcloud topic projections.

    resource keys
        Keys are names for resource resource items. For details run $ gcloud topic resource-keys. Most gcloud list commands have a --filter=EXPRESSION flag that selects resources to be listed. For details run $ gcloud topic filters.

Formats
A format expression has 3 parts:

    NAME
        name

    ATTRIBUTES
        [ [no-]attribute-name[=value] [, ... ] ]

    PROJECTION
        ( resource-key [, ...] ) NAME is required, ATTRIBUTES are optional, and PROJECTIONS may be required for some formats. Unknown attribute names are silently ignored.

Each gcloud list command has a default format expression. The --format flag can alter or replace the default. For example,
    --format='[box]'
adds box decorations to a default table, and
    --format=json
lists the resource in json format. The formats and format specific attributes are:

    config
        A dictionary of dictionaries in config style. The format attributes are:

        export
            Display the dictionary as a list of system specific environment export commands.

        unset
            Display the dictionary as a list of system specific environment unset commands.

    csv Comma Separated Values (http://www.ietf.org/rfc/rfc4180.txt) with no keys. This format requires a projection to define the values to be printed. The format attributes are:

        delimiter="string"
            The string printed between list value items, default ";".

        no-heading
            Disables the initial key name heading record.

        separator="string"
            The string printed between values, default ",".

        terminator="string"
            The string printed after each record, default "\n" (newline).

    default
        An alias for the yaml format.

    diff
        A unified diff of the first two projection columns. The format attributes are:

        format
            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'.

    disable
        Disables formatted output and does not consume the resources.

    flattened
        A flattened tree. Each output line contains one key:value pair. The format attributes are:

        no-pad
            Don't print space after the separator. The default adjusts the space to align the values into the same output column. Use no-pad for comparing resource outputs.

        separator=SEPARATOR
            Print SEPARATOR between the key and value. The default is ": ".

    get Equivalent to the value[no-transforms] format. Default transforms are not applied to the displayed values.

    json
        JSON (http://www.json.org), JavaScript Object Notation. The format attributes are:

        no-undefined
            Does not display resource data items with null values.

    list
        An ordered list of items. The format attributes are:

        always-display-title
            Display the title even if there are no records.

        compact
            Display all items in a record on one line.

    multi
        Each projection key must have a subformat defined by the :format=FORMAT-STRING attribute. For example,
        `--format="multi(data:format=json, info:format='table[box](a, b, c)')"`
    formats the data field as JSON and the info field as a boxed table.

    none
        Disables formatted output and consumes the resources.

    object
        Bypasses JSON-serialization and prints the object representation of each resource. The format attributes are:

        separator
            The line printed between resources.

        terminator
            The line printed after each resource.

    table
        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 --page-size=N is specified then output is grouped into tables with at most N rows. Headings, alignment and sorting are done per-page. The title, if any, is printed before the first table. The format attributes are:

        box Prints a box around the entire table and each cell, including the title if any.

        format=FORMAT-STRING
            Prints the key data indented by 4 spaces using FORMAT-STRING which can reference any of the supported formats.

        no-heading
            Disables the column headings.

        optional
            Does not display the column if it is empty.

        pad=N
            Sets the column horizontal pad to N spaces. The default is 1 for box, 2 otherwise.

        title=TITLE
            Prints a centered TITLE at the top of the table, within the table box if box is enabled.

    text
        An alias for the flattened format.

    value
        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. The format attributes are:

        delimiter="string"
            The string printed between list value items, default ";".

        quote
            "..." quote values that contain delimiter, separator or terminator strings.

        separator="string"
            The string printed between values, default "\t" (tab).

        terminator="string"
            The string printed after each record, default "\n" (newline).

    yaml
        YAML (http://www.yaml.org), YAML ain't markup language. The format attributes are:

        null=string
            Display string instead of null for null/None values.

        no-undefined
            Does not display resource data items with null values.

All formats have these attributes:

    disable
        Disables formatted output and does not consume the resources.

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

EXAMPLES
List a table of compute instance resources sorted by name with box decorations and title Instances:
    $ gcloud compute instances list \
        --format='table[box,title=Instances](name:sort=1,
     zone:title=zone, status)'
List the disk interfaces for all compute instances as a compact comma separated list:
    $ gcloud compute instances list \
        --format='value(disks[].interface.list())'
List the URIs for all compute instances:
    $ gcloud compute instances list --format='value(uri())'
List the project authenticated user email address:
    $ gcloud info --format='value(config.account)'