This page contains an overview of the gcloud command-line tool and its common command patterns and capabilities.
What is the gcloud command-line tool?
The gcloud command-line interface 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 CLI 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 the gcloud CLI to deploy App Engine applications, manage authentication, customize local configuration, and perform other tasks. Read the gcloud CLI reference to learn more about the capabilities of this tool.
The gcloud command-line tool cheat sheet
For a quick introduction to the gcloud command-line tool, a list of commonly used commands, and a look at how these commands are structured, refer to the gcloud command-line tool cheat sheet.
The gcloud CLI and Cloud SDK
The gcloud CLI 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 the gcloud command-line tool.
By default, the SDK installs those gcloud CLI commands that are at the General
Availability level only. Additional functionality is
available in SDK components named
alpha and beta. These components allow you to use the gcloud CLI to work
with Google Cloud Bigtable, Google Cloud Dataflow and other parts of the Cloud
Platform at earlier release levels than General Availability.
The gcloud CLI releases have the same version number as the SDK. The current SDK version is 336.0.0. You can download and install previous versions of the SDK from the download archive.
Downloading the gcloud command-line tool
You can download the latest version of Cloud SDK, which includes the gcloud command-line tool, from the download page.
Release levels
The gcloud CLI 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. |
The alpha and beta components are not installed by default when you install
the 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 command-line tool will prompt you to install it.
Command groups
Within each release level, gcloud CLI 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 CLI commands
You can run gcloud CLI commands from the command line in the same way you use other command-line tools. You can also run gcloud CLI commands from within scripts and other automations, for example, when using Jenkins to automate Cloud Platform tasks.
Properties
gcloud CLI properties are settings that affect the behavior of the gcloud CLI 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 command-line 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, refer to the Enabling accessibility features guide.
Configurations
A configuration is a named set of gcloud CLI 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. Within these configurations, 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 CLI provides a set of gcloud CLI-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 CLI 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 CLI 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, refer to the Scripting guide.
Prompting
To protect against unintended destructive actions, the gcloud CLI 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 the gcloud CLI
disables all interactive prompts when running gcloud CLI 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
with an appropriate level (debug, info, warning, error, critical, or none).
Determining output structure
By default, when a gcloud CLI 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 criteria you 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 command-line tool commands in the gcloud CLI Reference.