Cloud SDK

gcloud Tool Guide

gcloud command-line tool (installed together with Google Cloud SDK) can be used to manage both your development workflow and your Google Cloud Platform resources.

This guide describes development workflow related commands of gcloud 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.


To download and install the gcloud command-line tool, follow the Cloud SDK Installation and Quick Start instructions.


Accessing help

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

  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 executing gcloud help COMMAND. For example, gcloud init --help and gcloud help init commands are equivalent.

Back to top

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.

                         Get credentials via an existing refresh token.
                         Get credentials via the private key for a service
  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

The 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 gcloud auth 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 (or %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

Also, the $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.

Back to top

Installing components

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 gsutil, type the following command:

$ gcloud components update gsutil

Running the above update command installs the gsutil tool into 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 to run gsutil from the command line.

To update all of your installed components, type gcloud components update.

Back to top

Configuring components

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.

  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
region (unset)
zone (unset)
account = user@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 account and 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 example, running gcloud config set account newaccount@example.com 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 example, running gcloud config set compute/zone zone1 will set the zone property in the compute section.

Properties can be unset by using gcloud config unset, and listed using gcloud config list.

Configuration locations

gcloud configuration properties can be global or local. Global configuration properties are stored in $HOME/.config/gcloud directory.

Local configuration properties are typically created by running gcloud 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, gcloud scans the directory hierarchy from the current directory until the directory tree root. If a .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.

Back to top

Initializing a local Git repository

Every project in the Google Developers Console provides a free, Cloud-hosted Git repository that you can use for collaborative development.

Running gcloud init PROJECT on your workstation initializes a local Git repository and sets up the credentials required to access the Cloud repository as a remote.

$ 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:

  1. 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:

  2. To initialize this repository on your machine, 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 my-awesome-project-555/default directory.

  3. 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
  4. Now, push the code you pulled from GitHub to your Cloud repository:

    $ git push origin master

    You can now view the source files you pushed to the Cloud repository by navigating to the Source CodeBrowse page in Google Developers Console.

Local configurations

Running 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 B
After running these commands, the local directory structure will look like
    <Project A's source code>
    <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
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
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 running gcloud sql instances list from the right directory.

Back to top