Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



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.

Installation

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

Contents

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 |
                         sql
  command may be         help | init | interactive | 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.
  interactive            Use this tool in an interactive python shell.
  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.

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

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.

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
[component_manager]
snapshot_url (unset)
[core]
account = [email protected]
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 in the core section by running the following command. 

$ gcloud config set OPTION VALUE

So, running gcloud config set account [email protected] 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.

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 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 "Cloud Development → Releases" tab.

Running gcloud init PROJECT initializes and clones the remote repository associated with PROJECT , and sets up the required credentials for push-to-deploy . 

$ 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:
    https://source.developers.google.com/p/my-awesome-project-555/r/default

  2. 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 my-awesome-project-555/default directory.

  • 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 "Cloud Development → Releases" tab 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 !

    • 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 
    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 running gcloud sql instances list from the right directory.

    Back to top

    Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

    Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.