Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 45 ยท Getting Started

The gcloud CLI

Learn the gcloud command-line tool: install, log in, configurations, setting a project, flags, --format and --filter, and scripting, with runnable stand-ins.

The gcloud command-line tool is the main way to work with Google Cloud from a terminal. Everything you can click in the console can also be typed as a command, and commands can be saved in scripts, reviewed, and repeated exactly. That is why professionals prefer them for anything they will do more than once.

This lesson covers installing and signing in, keeping several setups apart with configurations, the shape of a command, and the two features that make gcloud pleasant in scripts: --filter and --format. You can try the console first in Console and Cloud Shell. The commands below need a real account, so they are read-only; the runnable examples are stand-ins that show how filtering and formatting work.

Cloud Shell already has gcloud installed and signed in. Install it locally only when you want to work from your own machine.

Install and sign in

Google publishes the Google Cloud CLI for Windows, macOS and Linux. After installing it, run the setup wizard and check the result:

Terminal
gcloud init
gcloud --version
gcloud auth list

If it is not installed yet, the steps depend on your system (read-only commands, since installers change your machine). Do this first, then come back to gcloud init:

Terminal
# Linux (Debian or Ubuntu): add Google's package repository, then install
sudo apt-get install apt-transport-https ca-certificates gnupg curl
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list
sudo apt-get update && sudo apt-get install google-cloud-cli

# Any Linux or macOS: the interactive archive installer
curl https://sdk.cloud.google.com | bash

# macOS with Homebrew
brew install --cask google-cloud-sdk

# Windows: download the installer from the Google Cloud CLI page, or use winget
winget install Google.CloudSDK

The tool behaves the same on every platform, so a command that works on your laptop works in a CI job. It also lets you drive every service from one place: Compute, Storage, BigQuery and more. For a zero-install start, Cloud Shell in the console already has gcloud ready (The Console and Cloud Shell).

gcloud init opens a browser to sign in, then asks you to pick a project and a default region. Later you can sign in again or add another account:

Terminal
gcloud auth login

There is a second kind of login that surprises beginners. gcloud auth login gives the command-line tool your identity. Your own program (a script that uses a Google Cloud client library) does not use it. For local development, a program finds credentials from Application Default Credentials, which you create separately:

Terminal
gcloud auth application-default login

Remember the pair: auth login is for gcloud, application-default login is for your code. How code gets credentials in production is covered in Service Accounts and Credentials.

The shape of a command

Commands are groups, then a sub-group, then an action, then the arguments:

Terminal
gcloud compute instances list
gcloud compute instances describe my-vm --zone=us-central1-a
gcloud storage buckets create gs://my-unique-bucket-name --location=us-central1

Anatomy of a command

Group A product area, such as compute or storage.
Sub-group The resource type, such as instances or buckets.
Action list, describe, create, delete, update.
Flags Settings such as --zone, --project, --format.

Run gcloud help or add --help to any level to see what is possible.

1 / 2

Flags use --name=value (a space instead of = also works). Boolean flags switch on by name, and many have a --no- opposite. A few flags work on almost every command: --project overrides the project for one command, --quiet skips confirmation prompts (useful in scripts, dangerous with delete), and --help prints documentation.

Configurations and the active project

Most commands need a project (see Projects and the Resource Hierarchy). Instead of repeating --project every time, gcloud stores defaults in a configuration:

Terminal
gcloud config set project my-project-id
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a
gcloud config list

A configuration is a named bundle of properties (account, project, region, zone). If you work on a personal project and a client project, create one configuration for each and switch between them:

Terminal
gcloud config configurations create client-a
gcloud config configurations list
gcloud config configurations activate default

Switching the active configuration changes the account and project for every later command, which prevents the classic mistake of deleting something in the wrong project. Before a risky command, run gcloud config list and read the project line. For one command only, the environment variable CLOUDSDK_CORE_PROJECT or the --project flag overrides the setting.

JS Stand-in: configurations decide the project

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The real tool stores configurations as files in your user profile, and a real project also has to exist and be accessible to your account. The stand-in only shows the lookup order: flag first, then the active configuration.

Reading output: --format

By default, gcloud prints a human-friendly table for list commands. For scripts you choose a format with --format:

Terminal
gcloud compute instances list --format=json
gcloud compute instances list --format=yaml
gcloud compute instances list --format="table(name, zone.basename(), status)"
gcloud compute instances list --format="value(name)"
gcloud compute instances list --format="csv(name,status)"

json and yaml print the full resource. table(...) picks columns and can apply small transforms such as basename(), which keeps only the last part of a long URL-like value. value(...) prints bare values with no header, one line per resource, which is ideal for loops and command substitution:

Terminal
for vm in $(gcloud compute instances list --format="value(name)"); do
  echo "Found $vm"
done

Choosing rows: --filter

--filter runs on the list of resources before formatting and keeps only matching resources. Keys can be nested with dots:

Terminal
gcloud compute instances list --filter="status=RUNNING"
gcloud compute instances list --filter="status=RUNNING AND zone:us-central1"
gcloud compute instances list --filter="name~^web-"
gcloud compute instances list --filter="labels.env=prod"

The main operators are = and != (equal), : (contains, or has the key), ~ (regular expression match), and <, >, <=, >=. Combine terms with AND, OR and NOT. Two companions help: --limit=5 caps the count, and --sort-by=name orders the results (prefix a key with ~ for descending order).

The details of the filter language are richer than this lesson, so check gcloud topic filters and gcloud topic formats when you need more.

A stand-in for --filter and --format

The program below takes a JSON list shaped like gcloud ... --format=json output and applies a simplified filter and value(...) format. It is a teaching model, not Google's implementation: it supports only dotted keys and the operators =, !=, : and ~.

Node.js Stand-in: filter and format JSON

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The real gcloud also works out transforms like zone.basename(), handles missing keys in its own way, and supports far more syntax. What carries over is the order of work: fetch resources, filter them, then format what is left.

Scripting tips

  • Use --format=value(...) or --format=json (with a JSON tool such as jq), never parse the default table.
  • Use --quiet only in automation, and put --project in the command so a script does not depend on whoever ran gcloud config set last.
  • Run with --log-http to see the underlying API calls when you want to learn how a command maps to the REST API.
  • Add gcloud components update to your routine, or use a package manager, so commands match the documentation you read. Output formats of beta and alpha commands (gcloud beta ...) can change.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command gives your own program Application Default Credentials for local development?

    auth login only signs in the gcloud tool. Client libraries look for Application Default Credentials, which application-default login creates.
  2. 2. You want a list of VM names only, one per line, for a shell loop. Which flag fits best?

    value(...) prints bare values with no header, which is easy to loop over. --filter chooses which resources, not which fields.
  3. 3. What does a gcloud configuration store?

    A configuration is a named set of properties. Activating another one switches the account and project used by later commands.
  4. 4. What does --filter="status=RUNNING AND zone:us-central1" do?

    Filters select resources to show. Equals compares exactly, and the colon operator tests whether a value contains the text.

Summary

  • gcloud init and gcloud auth login sign in the tool; gcloud auth application-default login is for your own code.
  • Commands read as group, sub-group, action, then flags.
  • Configurations store account, project, region and zone; check the active project before risky commands.
  • --filter selects resources and --format shapes the output; use value(...) or json in scripts.
  • The runnable examples are stand-ins; the gcloud commands need a real account.

Next: IAM: Principals, Roles and Policies