gcloud command-line tool (installed together with Google Cloud SDK)
can be used to manage both your development workflow and your Google Cloud
This guide describes development workflow related commands of
tool, while the resource management commands (like
gcloud compute for
Google Compute Engine resources, or
gcloud sql for Google Cloud SQL
resources) can be found in
Cloud Platform Tools guide.
InstallationTo download and install the
gcloudcommand-line tool, follow the Cloud SDK Installation and Quick Start instructions.
- Accessing help (gcloud help)
- Managing authentication and credentials (gcloud auth)
- Installing components (gcloud components)
- Configuring components (gcloud config)
- Initializing projects and setting up push-to-deploy (gcloud init)
- Other Cloud Platform tools (gcloud preview app, gcloud compute, gcloud sql, gcloud dns, and so on)
Simple usage guidelines are available by adding
-h onto the end of any
gcloud invocation. For example:
$ gcloud -h Usage: gcloud [optional flags]
group may be auth | components | compute | config | dns | preview | sql command may be help | init | version Manage Google Cloud Platform resources and your cloud developer workflow. optional flags: --help Display detailed help. --project PROJECT Google Cloud Platform project to use for this invocation. --quiet, -q Disable all interactive prompts. --user-output-enabled USER_OUTPUT_ENABLED Control whether user intended output is printed to the console. (true/false) --verbosity VERBOSITY Override the default verbosity for this command. This must be a standard logging verbosity level: [debug, info, warning, error, critical, none] (Default: [warning]). -h Print a summary help and exit. command groups: auth Manage oauth2 credentials for the Google Cloud SDK. components Install, update, or remove the tools in the Google Cloud SDK. compute Read and manipulate Google Compute Engine resources. config View and edit Google Cloud SDK properties. dns Manage Cloud DNS. preview Manage Preview CLI command groups. sql Manage Cloud SQL databases. commands: help Print a detailed help message. init Initialize a gcloud workspace in the current directory. version Print version information for Cloud SDK components.
More verbose help can be obtained by appending
--help flag, or
gcloud help COMMAND. For example,
gcloud help init commands are equivalent.
Managing authentication and credentials
The Cloud SDK uses Google's OAuth 2.0 service to authorize users and programs
to access Google APIs. The
gcloud auth command group manages your
Cloud SDK credentials for any number of accounts.
$ gcloud auth -h Usage: gcloud auth [optional flags]
command may be activate-refresh-token | activate-service-account | list | login | revoke Manage oauth2 credentials for the Google Cloud SDK. optional flags: --help Display detailed help. -h Print a summary help and exit. commands: activate-refresh-token Get credentials via an existing refresh token. activate-service-account Get credentials via the private key for a service account. list List the accounts for known credentials. login Get credentials for the tools in the Google Cloud SDK via a web flow. revoke Revoke authorization for credentials.
To authenticate with Google Cloud Platform, run the following command.
$ gcloud auth login
gcloud auth login command launches a web browser to perform
Google's OAuth 2.0 web flow. You will be asked to give permissions to "Google
Cloud SDK" to perform operations on your behalf, and the list of permissions is
sufficient to use any of the tools included in the Cloud SDK. Your credentials
do not expire (i.e. you should not need to re-run this command), but you can
repeat this process as many times as you'd like to add more accounts.
After accepting, go back to the terminal from where you ran
login and, if desired, inform it of a default project ID to use. If you
want to set or change the default project later, run the following command.
$ gcloud config set project PROJECT
You can see what accounts you've already added by running the following command:
$ gcloud auth list
You can select the active account by running the following command:
$ gcloud config set account ACCOUNT
All credential information is stored in the directory
%CLOUDSDK_CONFIG%\credentials on Windows), where
CLOUDSDK_CONFIG=$HOME/.config/gcloud on Linux and Mac, and
%APPDATA%\gcloud on Windows. Credentials for any account can be
revoked and deleted from your computer by running the following command:
$ gcloud auth revoke ACCOUNT
$CLOUDSDK_CONFIG/credentials directory can be safely
deleted at any time to remove the information from your machine, although
you'll have to reauthenticate in order to use any of the tools.
When you install the Google Cloud SDK, some components might be installed by default. To see a list of currently-installed components and a list of any available component updates, type the following command:
$ gcloud components list
To install additional components, type the
update command, followed
by the name of the component. For example, to install
the following command:
$ gcloud components update gsutil
Running the above
update command installs the
google-cloud-sdk/bin directory, and installs the tool's
dependencies elsewhere in the Cloud SDK. If you correctly added
google-cloud-sdk/bin to your
PATH, you will be able
gsutil from the command line.
To update all of your installed components, type
All tools in the Cloud SDK share some common configuration information, and
gcloud config is used to manage that configuration.
$ gcloud config -h Usage: gcloud config [optional flags]
command may be list | set | unset View and edit Google Cloud SDK properties. optional flags: --help Display detailed help. -h Print a summary help and exit. commands: list View Google Cloud SDK properties. set Edit Google Cloud SDK properties. unset Erase Google Cloud SDK properties.
To see all possible configuration properties, run the following command.
$ gcloud config list --all [compute] zone (unset) [core] account = email@example.com disable_usage_reporting = false project = cloudsdktest
The configuration properties are divided into sections, each of which contain one or more options.
Initially, the two important properties are the
project options, both in the
core section. You can change
the value of a property by running the following command.
$ gcloud config set SECTION/PROPERTY VALUE
The SECTION/ is optional when changing the value of
core properties. For
gcloud config set account firstname.lastname@example.org will change
the account used by the Cloud SDK tools to interact with Google APIs, and running
gcloud config set disable_usage_reporting true will tell the Cloud SDK to not
send anonymized usage data back to Google.
You must specify the SECTION/ when referring to properties in other sections. For
gcloud config set compute/zone zone1 will set the
zone property in the
Properties can be unset by using
gcloud config unset, and listed using
gcloud config list.
gcloud configuration properties can be global or local.
Global configuration properties are stored in
Local configuration properties are typically created by running
init (see below) and they can be stored in
.gcloud directories anywhere in a file system.
When a command in
gcloud config group is run,
the directory hierarchy from the current directory until the directory tree root. If
.gcloud directory is present in the hierarchy, it is used for storing
and reading local configuration properties; otherwise, global configuration
properties are used. This allows various
gcloud properties (e.g. a
project name) to be set automatically when navigating the file system.
See "Local configurations" subsection below for more information and examples.
Initializing projects and setting up push-to-deploy
For every new project created in Google Developers Console you can create a free, private Git repository by navigating to the Source Code → Releases page.
gcloud init PROJECT initializes and clones the remote
repository associated with
PROJECT, and sets up the required credentials
$ gcloud init -h Usage: gcloud init [optional flags] PROJECT Initialize a gcloud workspace in the current directory. optional flags: --help Display detailed help. -h Print a summary help and exit. positional arguments: PROJECT The Google Cloud project to tie the workspace to.
Here's an example workflow:
Create a new project on Google Developers Console. Let's assume that your project ID is "my-awesome-project-555".
A free, private Git repository will be automatically created for your project at this URL:
To initialize this repository on your machine and to setup push-to-deploy run the following command:
$ gcloud init my-awesome-project-555
After running this command, a Git repository will be initialized on your machine and any existing code will be cloned into
To add some sample code into your newly initialized project, change the current directory
$ cd my-awesome-project-555/default
and pull down a sample "Hello world" Python application, by running the following Git command:
$ git pull https://github.com/GoogleCloudPlatform/appengine-helloworld-python
When the command finishes, navigate to Source Code → Releases page in Google Developers Console, choose Deploy source only and click on Create pipeline.
Once the release pipeline is created, you can deploy your new "Hello world" application live to Google App Engine by performing a Git push from the command-line:
$ git push origin master
Your application should now be live at my-awesome-project-555.appspot.com!
gcloud init PROJECT also creates a local
configuration directory under
PROJECT/default/.gcloud. This implies that setting or listing
gcloud config properties in a directory hierarchy rooted at
PROJECT/default will only affect the local configuration properties.
This is particularly useful if you're switching between multiple projects with project-specific settings. For example, assume that two projects were initialized in the same top-level directory:
$ gcloud init A $ gcloud init BAfter running these commands, the local directory structure will look like
A/ .gcloud/ default/ .git/ <Project A's source code> B/ .gcloud/ default/ .git/ <Project B's source code>
Then, if you change the directory to
A and get the project property
stored in your local config, you'll see that it is set to A:
$ cd A $ gcloud config list project [core] project = A
Similarly, if you change the current directory to
B and get the
project, you'll see that it is set to B:
$ cd ../B $ gcloud config list project [core] project = B
If, for example, you had some Cloud SQL instances associated with projects
A and B then you could list the instances for an appropriate project simply by
gcloud sql instances list from the right directory.