gcloud CLI Explained: Commands, Auth, Config, and Examples

What gcloud CLI is

gcloud is the primary command-line interface for Google Cloud Platform. It is part of the Google Cloud SDK, which bundles gcloud with tools like gsutil (for Cloud Storage) and bq (for BigQuery). When most people say “install the Google Cloud SDK,” they mean getting gcloud.

gcloud runs on Linux, macOS, and Windows. Once installed and authenticated, it gives you full control over GCP resources from your terminal. You use it to create VMs, configure IAM, deploy Cloud Run services, manage Kubernetes clusters, enable APIs, inspect logs, and run any operation that the Cloud Console does through a browser.

If you have not installed gcloud yet, the installation guide covers macOS, Linux, and Windows setup and walks through the first-time gcloud init wizard that configures everything interactively.

What you can do with gcloud

gcloud covers every major GCP operation. Here are the categories you will reach for most:

• Create and manage resources. Launch VMs, create Cloud Storage buckets, deploy Cloud Run services, manage GKE clusters, set up databases, all from your terminal.

• Authenticate and manage accounts. Log in, switch between accounts, set up Application Default Credentials for local development, and activate service accounts.

• Configure projects and defaults. Set the active project, default region, and default zone so you do not have to add flags to every command.

• Manage IAM and service accounts. Grant and revoke roles, list bindings, and create or manage service accounts without opening a browser.

• Enable and inspect APIs. Turn on a Cloud API from the command line, list enabled APIs, and check whether a specific API is active in the current project.

• Inspect and debug resources. Describe running VMs, read recent logs, check operation status, and audit what is running in a project without navigating through the Console.

• Automate and script cloud tasks. Chain gcloud commands into shell scripts for repeatable setup, CI/CD pipelines, runbooks, and teardown procedures.

How gcloud commands are structured

Every gcloud command follows the same four-part pattern:

gcloud [GROUP] [SUBGROUP] [COMMAND] [FLAGS]

• GROUP: the GCP service or area: compute, storage, iam, run, container
• SUBGROUP: the resource type within that service: instances, buckets, service-accounts, clusters
• COMMAND: the action to perform: create, list, describe, delete, update
• FLAGS: options that modify the command: —zone=us-central1-a, —format=json, —quiet

The pattern is consistent across all services. Once you know it, you can guess new commands correctly before looking them up:

# List all VM instances in the current project
gcloud compute instances list

# Create a VM instance
gcloud compute instances create my-vm \
  --zone=us-central1-a \
  --machine-type=e2-micro

# Describe a specific instance in full detail
gcloud compute instances describe my-vm --zone=us-central1-a

# Delete a VM instance
gcloud compute instances delete my-vm --zone=us-central1-a

The same verb pattern applies across every group. gcloud run services list, gcloud storage buckets list, gcloud iam service-accounts list all follow the same shape. Learn it once and it works everywhere.

First gcloud commands to learn

If you are new to gcloud, start with these. They are safe, read-only or low-risk, and immediately useful for orienting yourself in a project.

# Log in with your Google account
gcloud auth login

# See all current settings (project, region, zone, account)
gcloud config list

# Set the active project
gcloud config set project PROJECT_ID

# List all projects your account has access to
gcloud projects list

# List all VM instances in the current project
gcloud compute instances list

# List all Cloud Run services in a region
gcloud run services list --region=us-central1

# List all APIs enabled in the current project
gcloud services list --enabled

# Get help for any command
gcloud compute instances create --help

The —help flag works on every command and subgroup. When you are not sure of the exact flags or syntax, run gcloud [command] —help before searching online. The built-in documentation includes examples and is always accurate.

How authentication works in gcloud

gcloud needs to know who you are before it can call any GCP API. There are two separate credential types, each serving a different purpose. Mixing them up is one of the most common beginner mistakes, and the errors it produces look like permission problems rather than authentication problems.

# Authenticate the gcloud CLI with your Google account
# (opens a browser window for interactive login)
gcloud auth login

# Set up Application Default Credentials for GCP client libraries
# (required separately when writing code that calls GCP APIs locally)
gcloud auth application-default login

# Authenticate as a service account using a key file
gcloud auth activate-service-account --key-file=key.json

# See which accounts are authenticated and which is currently active
gcloud auth list

When each credential type applies

• gcloud auth login is for running gcloud commands interactively in your terminal. Use this when setting up gcloud for the first time or when switching accounts.

• gcloud auth application-default login is for local development where your code uses GCP client libraries. The libraries pick up ADC credentials automatically, so this command makes your personal Google account available to them without hardcoding anything.

• Service account key activation is for running gcloud in automated environments (scripts, CI/CD) where interactive browser login is not possible. See the service accounts guide for when to use a service account versus your personal identity.

• Attached service account (on GCP infrastructure) applies when your code runs on Cloud Run, GKE, or Compute Engine. The attached service account provides ADC automatically via the metadata server. No key files or login commands required.

Understanding the difference between your personal identity and service accounts is important for getting authentication right in real projects.

How configuration works in gcloud

gcloud stores a configuration with your active project, region, and zone. Setting these defaults saves you from typing —project, —region, and —zone on every command.

# See all current configuration settings
gcloud config list

# Set the active project
gcloud config set project my-project-id

# Set a default region and zone
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

# Check what a single setting is currently set to
gcloud config get-value project
gcloud config get-value compute/region

# Unset a value and return to requiring the flag explicitly
gcloud config unset compute/zone

The active project matters most. Commands that create, list, or modify resources operate on the project in your configuration unless you override it with —project=PROJECT_ID for a single command. Setting the wrong project and running a destructive command is one of the more painful beginner mistakes.

Setting a default region and zone is also worth doing early. Without them, region-specific commands either prompt interactively or fail with an error. Most teams pick the region closest to their users and set it once per project configuration.

Named configurations for multi-project work

If you work across multiple GCP projects, switching settings one by one each time is slow and error-prone. Named configurations let you save a full set of settings under a name and switch all of them in one command.

Each named configuration stores a project, region, zone, and account. A developer working across dev, staging, and production would create three separate configurations:

# Create a named configuration for production
gcloud config configurations create prod
gcloud config set project acme-api-prod
gcloud config set compute/region europe-west1
gcloud config set account alice@acme.com

# Create another configuration for development
gcloud config configurations create dev
gcloud config set project acme-api-dev
gcloud config set compute/region us-central1
gcloud config set account alice@acme.com

# Switch to the production configuration
gcloud config configurations activate prod

# Switch back to development
gcloud config configurations activate dev

# List all configurations and see which is active
gcloud config configurations list

gcloud vs Cloud Console: when to use each

gcloud and the Cloud Console call the same underlying GCP APIs. They are not competitors. Most cloud engineers use both daily. The question is which one is faster for the task in front of you.

A practical rule: reach for the Console when you are exploring, checking live status, or debugging visually. Reach for gcloud when you are building, automating, or doing something you will repeat. Over time, most engineers move more daily work into gcloud commands because commands are reproducible and can live in version control.

When gcloud is the right tool

Certain workflows become significantly easier once you reach for gcloud instead of the browser:

• Repeatable setup. Creating the same set of resources across dev, staging, and production is tedious in the Console and error-prone when done by hand. A gcloud script runs identically every time.

• CI/CD pipelines. Deployment pipelines (GitHub Actions, Cloud Build, Jenkins) use gcloud commands to deploy Cloud Run services, update GKE configurations, or push container images. No browser involved.

• Automation and scripting. Scheduled cleanup scripts, resource inventory checks, and automated environment teardown all benefit from gcloud’s consistent output formats and scriptable behaviour.

• Multi-project work. Switching between projects with named configurations is faster than navigating the project picker in the Console and waiting for the page to reload.

• Faster troubleshooting. Listing all running VMs, checking which APIs are enabled, or reading recent log entries is often one command away in the terminal, which is faster than navigating several pages in the Console.

• Documentation and runbooks. A gcloud command in a runbook can be copied and executed directly. A Console instruction like “click the button next to the resource name” ages poorly and breaks when the UI changes.

• Working without a browser. SSH sessions, remote servers, and Cloud Shell all work fine with gcloud. The Console is not always available.

Output formats

By default, gcloud returns human-readable tables. These work well for quick reading but are not useful in scripts. Use —format to control what you get:

# Default table output (human-readable)
gcloud compute instances list

# JSON output (pipe to jq, use in scripts, parse in code)
gcloud compute instances list --format=json

# YAML output (readable and structured)
gcloud compute instances list --format=yaml

# Custom table showing only the columns you care about
gcloud compute instances list \
  --format="table(name,zone,status,machineType)"

# Extract a single value for use in a shell variable
gcloud compute instances describe my-vm \
  --zone=us-central1-a \
  --format="value(networkInterfaces[0].accessConfigs[0].natIP)"

The value() format is particularly useful in scripts. It extracts a single field as plain text with no table headers or decorations, so you can assign it directly to a shell variable:

IP=$(gcloud compute instances describe my-vm \
  --zone=us-central1-a \
  --format="value(networkInterfaces[0].accessConfigs[0].natIP)")

echo "Connecting to: $IP"
ssh user@"$IP"

Global flags worth knowing

These flags work on every gcloud command and are worth learning early:

• —project=PROJECT_ID: override the active project for one command without changing your configuration. Useful when you need to check something in another project quickly.

• —quiet / -q: suppress confirmation prompts. Essential in scripts where interactive input is not possible.

• —verbosity=debug: print the underlying HTTP requests gcloud makes. Invaluable when a command fails with an unclear error. Shows the exact API call and the full response body.

• —async: return immediately after submitting a long-running operation instead of waiting for it to complete. The operation continues in the background.

• —format=FORMAT: control the output format for any command. See the output formats section above.

• —help / -h: show documentation, flags, and examples for any command or subgroup. Run this before searching online.

# Delete a VM without the confirmation prompt, in a specific project
gcloud compute instances delete my-vm \
  --zone=us-central1-a \
  --project=my-other-project \
  --quiet

# See the HTTP calls gcloud makes under the hood
gcloud compute instances list --verbosity=debug 2>&1 | head -50

# Start a long-running cluster creation and return immediately
gcloud container clusters create my-cluster \
  --zone=us-central1-a \
  --async

A basic workflow for getting started

If you have just installed gcloud or are setting it up on a new machine, follow these steps in order. Each one builds on the last.

1. Install gcloud. Follow the installation guide for your operating system. Run gcloud version to confirm it worked.

2. Log in. Run gcloud auth login. A browser window opens. Sign in with the Google account that has access to your GCP project. gcloud stores the credential locally.

3. Set your project. Run gcloud config set project PROJECT_ID with your actual project ID, not the project name. Find the ID in the Cloud Console project picker or by running gcloud projects list.

4. Set a default region. Run gcloud config set compute/region REGION with the region closest to your users or where your resources will live. See regions and zones if you are not sure which to pick.

5. Confirm your configuration. Run gcloud config list to verify the project, region, and account all look correct.

6. Run a read-only command first. Try gcloud projects list or gcloud services list —enabled to confirm authentication and project settings are working before doing anything that creates or modifies resources.

7. Set up Application Default Credentials if you are writing code. Run gcloud auth application-default login if you are building an application that calls GCP APIs using client libraries. Make sure the relevant APIs are enabled in your project first.