gcloud Overview

This page contains an overview of the gcloud command-line tool and its common command patterns and quirks.

What is gcloud?

gcloud is a tool that provides the primary command-line interface to Google Cloud Platform. You can use this tool to perform many common platform tasks either from the command-line or in scripts and other automations.

For example, you can use gcloud to create and manage:

• Google Compute Engine virtual machine instances and other resources
• Google Cloud SQL instances
• Google Kubernetes Engine clusters
• Google Cloud Dataproc clusters and jobs
• Google Cloud DNS managed zones and record sets
• Google Cloud Deployment manager deployments

You can also use gcloud to deploy App Engine applications and perform other tasks. Read the gcloud reference to learn more about the capabilities of this tool.

gcloud and the SDK

gcloud is a part of the Google Cloud SDK. You must download and install the SDK on your system and initialize it before you can use gcloud.

By default, the SDK installs those gcloud commands that are at the General Availability and Preview levels only. Additional functionality is available in SDK components named alpha and beta. These components allow you to use gcloud to work with Google Cloud Bigtable, Google Cloud Dataflow and other parts of the Cloud Platform at earlier release levels than General Availability.

gcloud releases have the same version number as the SDK. The current SDK version is 223.0.0. You can download and install previous versions of the SDK from the download archive.

Note: gcloud is available automatically in Google Cloud Shell. If you are using Cloud Shell, you do not need to install gcloud manually in order to use it.

Downloading gcloud

You can download the latest version of Cloud SDK, which includes gcloud, from the download page.

Release levels

gcloud commands have the following release levels:

Release level	Label	Description
General Availability	None	Commands are considered fully stable and available for production use. Advance warnings will be made for commands that break current functionality and documented in the release notes.
Beta	beta	Commands are functionally complete, but may still have some outstanding issues. Breaking changes to these commands may be made without notice.
Alpha	alpha	Commands are in early release and may change without notice.
Preview	preview	Commands may be unstable and may change without notice.

The alpha and beta components are not installed by default when you install the SDK. You must install these separately using the gcloud components install command. If you try to run an alpha or beta command and the corresponding component is not installed, gcloud will prompt you to install it.

Command groups

Within each release level, gcloud commands are organized into a nested hierarchy of command groups, each of which represents a product or feature of the Cloud Platform or its functional subgroups.

For example:

Command group	Description
gcloud compute	Commands related to Compute Engine in general availability
gcloud compute instances	Commands related to Compute Engine instances in general availability
gcloud beta compute	Commands related to Compute Engine in Beta
gcloud alpha app	Commands related to managing App Engine deployments in Alpha

Running gcloud commands

You can run gcloud commands from the command line in the same way you use other command-line tools. You can also run gcloud commands from within scripts and other automations, for example, when using Jenkins to automate Cloud Platform tasks.

Note: gcloud reference documentation and examples use backslashes, \, to denote long commands. You can execute these commands as-is (Windows users can use ^ instead of \). If you'd like to remove the backslashes, be sure to remove newlines as well to ensure the command is read as a single line.

Properties

gcloud properties are settings that affect the behavior of gcloud and other Cloud SDK tools. Some of these properties can be set by either global or command flags - in which case, the value set by the flag takes precedence.

A list of available properties can be found here.

Configurations

A configuration is a named set of gcloud properties. It works like a profile, essentially.

Starting off with Cloud SDK, you'll work with a single configuration named default and you can set properties by running either gcloud init or gcloud config set. This single default configuration is suitable for most use cases.

If you'd like to work with multiple projects or authorization accounts, you can set up multiple configurations with gcloud config configurations create and switch among them accordingly.

For a detailed account of these concepts, see these explorations of configurations and their management.

Global flags

gcloud provides a set of gcloud-wide flags that govern the behavior of commands on a per-invocation level. Flags override any values set in SDK properties.

Positional Arguments and Flags

While both positional arguments and flags affect the output of a gcloud command, there is a subtle difference in their use cases. A positional argument is used to define an entity on which a command operates while a flag is required to set a variation in a command's behaviour.

Use of stdout and stderr

Successful output of gcloud commands is written to stdout. All other types of responses - prompts, warnings, and errors - are written to stderr. Note that anything written to stderr is not stable and should not be scripted against.

For a definitive list of guidelines on handling output, read this section.

Prompting

To protect against unintended destructive actions, gcloud will confirm your intentions before executing commands such as gcloud projects delete.

You can also expect prompts if you were to create a Google Compute Engine virtual machine instance, say 'test-instance', using gcloud compute instances create test-instance. You will be asked to choose a zone to create the instance in.

To disable prompting, use the --quiet flag.

Note, the wording of prompts can change and should not be scripted against.

Suppressing prompting, writing to the terminal, and logging

The --quiet flag (also, -q) for gcloud disables all interactive prompts when running gcloud commands and comes in handy when scripting. In the event input is needed, defaults will be used. If there aren't any, an error will be raised.

To suppress printing of command output to standard output and standard error in the terminal, use the --no-user-output-enabled flag.

To adjust verbosity of logs instead, use the --verbosity flag and define the appropriate level.

Determining output structure

By default, when a gcloud command returns a list of resources, they are pretty-printed to standard output. To produce more meaningful output, the format, filter and projection flags allow you to finetune your output.

If you'd like to define just the format of your output, use the --format flag to produce a tabulated or flattened version of your output (for interactive display) or a machine-readable version of the output (json, csv, yaml, value).

To format a list of keys that select resource data values, use projections. To further refine your output to a criteria you'd like to define, use filter.

If you'd like to work through a quick interactive tutorial to help get you familiar with filter and format functionality, follow the link below.

What's next

• Learn more about gcloud commands in the gcloud Reference.