This page contains an overview of the gcloud command-line tool and
its common command patterns and capabilities.
What is the gcloud tool?
The gcloud command-line tool is the primary CLI tool to create and manage
Google Cloud resources. 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 the gcloud tool to create and manage:
- Compute Engine virtual machine instances and other resources
- Cloud SQL instances
- Google Kubernetes Engine clusters
- Dataproc clusters and jobs
- Cloud DNS managed zones and record sets
- Cloud Deployment Manager deployments
You can also use the gcloud tool to deploy App Engine
applications, manage authentication, customize local configuration, and perform
other tasks. To learn more about the capabilities of gcloud tool,
see the gcloud tool reference.
The gcloud tool cheat sheet
For a quick introduction to the gcloud tool, a list of commonly
used commands, and a look at how these commands are structured, see the
gcloud tool cheat sheet.
The gcloud tool and Cloud SDK
The gcloud tool is a part of the Cloud SDK.
Before you can use the gcloud tool, you must
download and install the Cloud SDK on your
system and initialize Cloud SDK .
By default, the Cloud SDK installs the gcloud tool
commands that are at the General Availability level. Additional functionality is
available in Cloud SDK
components named alpha and beta. These components
allow you to use the gcloud tool to work with Cloud Bigtable,
Dataflow and other parts of the Google Cloud at earlier release
levels than General Availability.
The gcloud tool releases have the same version number as the Cloud SDK.
The current Cloud SDK version is 368.0.0. You can download and
install previous versions of the Cloud SDK from the
download archive.
Downloading the gcloud tool
You can download the latest version of Cloud SDK, which includes the
gcloud tool, from the download page.
Release levels
The gcloud tool commands have the following release levels:
| Release level | Label | Description |
|---|---|---|
| General Availability | None | Commands are considered fully stable and available for production use. For advance notice of changes to commands that break current functionality, see the release notes. |
| Beta | beta |
Commands are functionally complete, but could still have some outstanding issues. Breaking changes to these commands can be made without notice. |
| Alpha | alpha |
Commands are in early release and may change without notice. |
The alpha and beta components are not installed by default when you install
the Cloud SDK. You must install these components
separately using the gcloud components install command. If you try to run an
alpha or beta command and the corresponding component is not installed,
the gcloud tool prompts you to install it.
Command groups
Within each release level, gcloud tool commands are organized into a
nested hierarchy of command groups, each of which represents a product or
feature of Google Cloud 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 tool commands
You can run gcloud tool commands from the command line in the same
way you use other command-line tools. You can also run gcloud tool
commands from scripts and other automations,
for example, when using Jenkins to automate Google Cloud tasks.
Properties
gcloud tool properties are settings that
affect the behavior of the gcloud tool 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.
Enabling accessibility features
For a more streamlined screen reader experience, the gcloud tool
comes with an accessibility/screen_reader property.
To enable this property, run:
gcloud config set accessibility/screen_reader true
For more details about the accessibility features that come with the gcloud command-line tool, see the Enabling accessibility features guide.
Configurations
A configuration is a named set of gcloud tool properties. A
configuration works like a profile.
When you start using Cloud SDK, you'll work with a single
configuration named default and you can set properties by running
gcloud init or gcloud config set. This single default configuration is
suitable for most use cases.
To work with multiple projects or authorization accounts, you can set up
multiple configurations with gcloud config configurations create and switch
among the configurations. Within a configuration, you can customize properties.
For example, to set your project within an active configuration
use the project property:
gcloud config set project <project-id>
For a detailed account of these concepts, see the Configurations guide.
Global flags
The gcloud tool provides a set of
gcloud tool-wide flags
that govern the behavior of commands on a per-invocation level. Flags override
values set in Cloud SDK properties.
Positional arguments and flags
While positional arguments and flags affect the output of a
gcloud tool 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
The output of successful gcloud tool commands is written to
stdout. All other types of responses - prompts, warnings, and errors - are
written to stderr. Do not script against responses written to stderr because
these responses aren't stable.
For guidelines on handling output, refer to the Scripting guide.
Prompting
To protect against unintended destructive actions, the gcloud tool
confirms your intentions before executing commands such as
gcloud projects delete.
You can also expect prompts if you were to create a Compute Engine
virtual machine instance using gcloud compute instances create test-instance.
You are prompted to choose a zone to create the instance in.
To disable prompting, use the --quiet flag.
Do not script against the wording of prompts because the wording can change.
Suppressing prompting, writing to the terminal, and logging
The --quiet flag (also, -q) for the
gcloud tool
disables all interactive prompts when running gcloud tool commands
and is useful for scripting. If input is needed, defaults are used. If there
isn't a default, an error is 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, specify a verbosity level (debug, info, warning,
error, critical, or none) using the
--verbosity flag.
Determining output structure
By default, when a gcloud tool command returns a list of resources,
the resources are pretty-printed to standard output. To produce more meaningful
output, the format, filter, and projection flags allow you to fine-tune
your output.
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 criteria you define, use
filter.
To familiarize yourself with filter and format functionality, you can complete a quick interactive tutorial by clicking Open in Cloud Shell.
What's next
- Learn more about
gcloudtool commands in thegcloudtool reference.