gcloud CLI and Cloud Shell

The gcloud CLI is the primary command-line interface for Google Cloud, and Cloud Shell provides a free, browser-based terminal with everything pre-installed. This guide covers installation, authentication, command structure, output formatting, and when to use each tool.

Note: This page is current as of May 2026. Pre-installed Cloud Shell tool versions and gcloud CLI features change regularly. Verify current details in the official Google Cloud documentation.

What Is gcloud CLI

The gcloud CLI is the official command-line tool for creating and managing Google Cloud resources. It is part of the Google Cloud SDK, which also includes:

Tool	Purpose	Status
gcloud	Manage all Google Cloud resources	Active, primary CLI
gcloud storage	Cloud Storage operations (copy, list, remove)	Recommended replacement for `gsutil`
bq	BigQuery operations	Separate CLI, still maintained
kubectl	Kubernetes / GKE cluster management	Separate binary, installed via gcloud components

The gcloud CLI wraps Google Cloud REST APIs so you can manage resources from a terminal or script. It handles authentication, request construction, and response formatting automatically.

Note: The legacy gsutil tool is minimally maintained. Use gcloud storage commands for all new Cloud Storage workflows.

Installation

Platform	Method	Command
macOS	Homebrew	`brew install --cask gcloud-cli`
macOS	Tarball	Download from cloud.google.com/sdk/docs/install
Linux (Debian/Ubuntu)	apt	Add Google repo, then `apt install google-cloud-cli`
Linux (RHEL/Fedora)	dnf	Add Google repo, then `dnf install google-cloud-cli`
Linux	Tarball	Download and run `./google-cloud-sdk/install.sh`
Windows	Installer	Download `GoogleCloudSDKInstaller.exe`
Cloud Shell	Pre-installed	No installation needed

macOS (Homebrew)

brew install --cask gcloud-cli

Linux (Debian/Ubuntu)

# Add the Google Cloud SDK repository
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 -a /etc/apt/sources.list.d/google-cloud-sdk.list
 
# Install
sudo apt-get update && sudo apt-get install google-cloud-cli

Verify Installation

gcloud version

Keep gcloud CLI Updated

gcloud components update

The gcloud CLI releases weekly. Run gcloud components update periodically when you installed from the interactive installer. If you installed with a package manager such as apt, dnf, or Homebrew, update through that package manager instead.

Tip: Cloud Shell already has gcloud CLI installed and handles browser-based authorization for you. See the Google Cloud Shell section below for details.

Authentication

gcloud CLI supports three authentication methods depending on how you use it.

gcloud auth login

Opens a browser for OAuth2 authentication. Credentials are stored locally and used for subsequent gcloud commands. Use this for interactive terminal sessions.

Application Default Credentials (ADC)

gcloud auth application-default login

Also opens a browser, but stores credentials in a well-known file (~/.config/gcloud/application_default_credentials.json). Client libraries (Python, Java, Node.js, Go) pick up these credentials automatically when running code locally that calls Google Cloud APIs.

The difference: gcloud auth login authorizes the gcloud CLI itself. gcloud auth application-default login authorizes your application code.

Service Account Authentication

gcloud auth activate-service-account --key-file=service-account-key.json

Uses a service account JSON key file. Ideal for CI/CD pipelines, automated scripts, and server environments where browser-based login is not possible.

Warning: Avoid downloading service account keys when possible. Prefer Workload Identity for GKE, Workload Identity Federation for other environments, or the default service account on Compute Engine and Cloud Run. Downloaded keys are a security risk if leaked.

Check Authenticated Accounts

gcloud auth list

Command Structure

All gcloud commands follow this pattern:

gcloud [RELEASE_LEVEL] GROUP SUBGROUP ACTION [ARGS] [FLAGS]

Component	Required	Example	Description
`gcloud`	Yes	`gcloud`	The base command
Release level	No	`alpha`, `beta`	Access pre-GA features
Group	Yes	`compute`, `storage`, `iam`	Top-level service area
Subgroup	Varies	`instances`, `firewall-rules`	Resource type
Action	Yes	`create`, `list`, `describe`, `delete`	Operation to perform
Args	Varies	`my-vm`, `--zone=us-central1-a`	Resource names and flags

Example breakdown:

gcloud compute instances create my-vm --zone=us-central1-a --machine-type=e2-micro
       │       │         │       │      │                  │
       group   subgroup  action  name   flag               flag

Release Levels

Level	Prefix	Stability	When to Use
GA	(none)	Stable, production-ready	Default for all common operations
Preview	`gcloud preview`	Feature-complete, may change	New features before GA
Beta	`gcloud beta`	Near-complete, some changes	Features not yet GA
Alpha	`gcloud alpha`	Early access, may break	Experimental features

Preview, alpha, and beta components are not installed by default. Install them with:

gcloud components install preview
gcloud components install alpha
gcloud components install beta

Note: Most common operations are GA and need no release level prefix. Only use preview, alpha, or beta when you need features not yet in GA.

Common Global Flags

These flags work across all gcloud commands:

Flag	Purpose	Example
`--project`	Override the active project	`--project=my-project`
`--zone`	Set Compute Engine zone	`--zone=us-central1-a`
`--region`	Set Compute Engine region	`--region=us-central1`
`--format`	Control output format	`--format=json`
`--filter`	Filter results by expression	`--filter="status=RUNNING"`
`--quiet` / `-q`	Disable interactive prompts	`--quiet` (essential for scripts)
`--verbosity`	Log detail level	`--verbosity=error`
`--help`	Show help for any command	`gcloud compute instances create --help`
`--dry-run`	Preview without executing	`--dry-run` (supported by some commands)

Tip: Use --help liberally. gcloud CLI help is comprehensive and includes examples at every level: gcloud help, gcloud compute --help, gcloud compute instances create --help.

Output Formats

Control how gcloud CLI displays results:

Format	Best For	Example
`table`	Human-readable terminal output	`--format="table(name,zone,status)"`
`json`	Scripting, piping to `jq`	`--format=json`
`yaml`	Configuration, readable structure	`--format=yaml`
`csv`	Spreadsheet import	`--format=csv`
`value`	Extract specific fields, piping	`--format="value(name)"`

Projections (Select Specific Fields)

# Show only name, zone, and status in a table
gcloud compute instances list --format="table(name,zone,status)"
 
# Extract just the external IP of a VM
gcloud compute instances describe my-vm --zone=us-central1-a \
  --format="get(networkInterfaces[0].accessConfigs[0].natIP)"
 
# Use machineType.basename() to show just the type name
gcloud compute instances list --format="table(name,machineType.basename())"

Filtering

# Running instances only
gcloud compute instances list --filter="status=RUNNING"
 
# Instances in us-central1 with the http-server tag
gcloud compute instances list --filter="zone~us-central1 AND tags:http-server"

Configuration Management

A configuration is a named set of gcloud properties (project, zone, region, account). Think of it as a profile.

Default Configuration

# Set the active project
gcloud config set project my-project-id
 
# Set default zone and region (saves typing --zone and --region every time)
gcloud config set compute/zone us-central1-a
gcloud config set compute/region us-central1
 
# View current configuration
gcloud config list

Named Configurations

Named configurations let you switch between projects or accounts without re-authenticating:

# Create a configuration for a work project
gcloud config configurations create work-project
 
# Set properties for it
gcloud config set project my-work-project
gcloud config set compute/zone us-central1-a
 
# Create a configuration for a personal project
gcloud config configurations create personal-project
gcloud config set project my-personal-project
 
# Switch between them
gcloud config configurations activate work-project
gcloud config configurations activate personal-project
 
# List all configurations
gcloud config configurations list

You can also override the configuration per command:

gcloud compute instances list --configuration=work-project

Tip: Use named configurations if you work with multiple Google Cloud projects or accounts. Each configuration stores its own project, zone, region, and account credentials.

Common Commands by Service

Quick-reference for the most frequently used commands. See the dedicated articles for detailed coverage.

Compute Engine

# List all VM instances across all zones
gcloud compute instances list
 
# Create a VM
gcloud compute instances create my-vm \
  --machine-type=e2-micro \
  --zone=us-central1-a \
  --image-family=debian-12 \
  --image-project=debian-cloud
 
# SSH into a VM
gcloud compute ssh my-vm --zone=us-central1-a
 
# Stop, start, delete
gcloud compute instances stop my-vm --zone=us-central1-a
gcloud compute instances start my-vm --zone=us-central1-a
gcloud compute instances delete my-vm --zone=us-central1-a

See Creating Your First VM for a detailed walkthrough.

Cloud Storage

# Create a bucket
gcloud storage buckets create gs://my-bucket --location=us-central1
 
# Copy files
gcloud storage cp local-file.txt gs://my-bucket/
 
# List objects
gcloud storage ls gs://my-bucket/
 
# Remove a bucket
gcloud storage rm -r gs://my-bucket

Networking

# Create a VPC network
gcloud compute networks create my-vpc --subnet-mode=custom
 
# Create a subnet
gcloud compute networks subnets create my-subnet \
  --network=my-vpc --range=10.0.0.0/24 --region=us-central1
 
# Create a firewall rule
gcloud compute firewall-rules create allow-http \
  --network=my-vpc --allow=tcp:80 --source-ranges=0.0.0.0/0

IAM and Projects

# List projects
gcloud projects list
 
# Create a service account
gcloud iam service-accounts create my-sa --display-name="My Service Account"
 
# Grant a role
gcloud projects add-iam-policy-binding my-project-id \
  --member="user:[email protected]" \
  --role="roles/storage.objectViewer"

GKE (Kubernetes)

# Create a cluster
gcloud container clusters create my-cluster --num-nodes=3 --zone=us-central1-a
 
# Get kubectl credentials
gcloud container clusters get-credentials my-cluster --zone=us-central1-a

Cloud Run

# Deploy a service
gcloud run deploy my-service --image=gcr.io/my-project/my-image --region=us-central1
 
# List services
gcloud run services list --region=us-central1

gcloud CLI vs REST API vs Console

Aspect	gcloud CLI	REST API	Console
Best for	Scripting, automation, local development	Custom applications, integrations	Exploration, one-off tasks, learning
Auth	Built-in OAuth handling	Manual token management	Browser-based login
Repeatability	High (scriptable)	High (programmatic)	Low (manual clicks)
Coverage	Most GA services	All services (source of truth)	Most common operations
Learning curve	Moderate	High	Low
Output	Structured (json, yaml, table, csv)	JSON only	Visual UI

In practice: Most engineers use all three. Console for exploration, gcloud CLI for daily operations and scripts, Terraform or Pulumi for production infrastructure.

Tips

--quiet for scripts — Disables all interactive prompts. Essential for CI/CD:

gcloud compute instances delete my-vm --zone=us-central1-a --quiet

Shell completion — Add to your shell config for tab completion:

# Bash
source <(gcloud completion bash)
 
# Zsh
source <(gcloud completion zsh)

Useful aliases — Save keystrokes for frequent operations:

alias glist='gcloud compute instances list --format="table(name,zone,status)"'
alias gssh='gcloud compute ssh'
alias gproj='gcloud config set project'

gcloud info — Quick diagnostic of your installation, configuration, and auth status.

gsutil to gcloud storage transition — The legacy gsutil tool is minimally maintained. Use gcloud storage instead:

# Old: gsutil ls gs://my-bucket
# New:
gcloud storage ls gs://my-bucket
 
# Old: gsutil cp file.txt gs://my-bucket
# New:
gcloud storage cp file.txt gs://my-bucket

Google Cloud Shell

Google Cloud Shell is a free, browser-based shell environment that provides a fully provisioned Debian VM with gcloud CLI and common development tools pre-installed. Activate it from the Google Cloud Console by clicking the >_ icon in the top-right toolbar.

No installation, no configuration. Open a browser, click the icon, start typing commands.

Pre-installed Tools

Tool	Purpose
gcloud CLI	Google Cloud resource management
kubectl	Kubernetes / GKE management
Docker	Container build and run
Terraform	Infrastructure as Code
git	Version control
jq, yq	JSON/YAML processing
make, gcc	Build tools
npm, pip, uv	Package managers
MySQL client	Database connectivity
Cloud Shell Editor	Built-in IDE (Code OSS)

Pre-installed Language Runtimes

Runtime	Version
Go	Latest stable
Python	3.12
Node.js	LTS
Java	JRE/JDK 17
.NET	SDK 6.0, 7.0, 8.0
PHP	8.3
Ruby	3.2

The Cloud Shell container image is updated weekly with current tool versions.

Cloud Shell Editor

The built-in editor is based on Code OSS, the open-source project behind Visual Studio Code. Click Open Editor in the Cloud Shell toolbar to launch it.

Features include:

File explorer and multi-file editor with syntax highlighting
Integrated terminal (same as Cloud Shell terminal)
Cloud Code extension for Kubernetes, Cloud Run, and App Engine development
Built-in Git integration
Can open in a standalone browser window

Persistent Storage

Cloud Shell provides 5 GB of free persistent disk mounted at $HOME:

What Persists	What Does Not
Files in `$HOME`	System-level packages installed outside `$HOME`
`.bashrc`, `.vimrc`, shell configs	Running processes
gcloud CLI preferences (if in `$HOME`)	Software installed outside `$HOME`
Git repositories, scripts	Temporary files in `/tmp`

Warning: Files outside your $HOME directory are lost when Cloud Shell restarts. Always save work in $HOME or push it to a Git repository.

Your $HOME directory is deleted after 120 days of inactivity. For long-term storage, use Cloud Storage buckets instead.

Web Preview

Run web applications on the Cloud Shell VM and preview them in the browser. Supported ports: 2000-65000. Access via the Web Preview button in the toolbar.

Example: start a Python HTTP server and preview it:

python3 -m http.server 8080

Then click Web Preview > Preview on port 8080 to see it in the browser.

Ephemeral Mode

Start Cloud Shell without persistent disk for faster startup. All files are lost when the session ends.

Access via the Cloud Shell menu: More > Ephemeral mode
Or use the URL: https://shell.cloud.google.com/?ephemeral=true
Can be set as the default mode

Use ephemeral mode for quick, disposable tasks where you do not need to keep any files.

Limitations

Limit	Value
Weekly usage quota	50 hours per week
Maximum session duration	12 hours
Idle timeout	40 minutes (session disconnects)
Inactivity deletion	120 days (persistent disk deleted)
Persistent disk size	5 GB (cannot expand)
VM region	Auto-assigned (cannot choose)

Cloud Shell is intended for interactive development and management. It is not a production server.

Note: If you exceed the 50-hour weekly quota, Cloud Shell is unavailable until the quota resets. Check the Usage quota dialog in Cloud Shell for your current reset time. For heavy development, install gcloud CLI locally or use Cloud Workstations (paid, managed development environments without weekly limits).

When to Use Cloud Shell vs Local gcloud CLI

Situation	Cloud Shell	Local gcloud CLI
Quick experiment or tutorial	Use
Machine without gcloud installed	Use
Production scripts or CI/CD		Use
Long-running development session		Use
Multiple project contexts		Use (named configurations)
Need custom software installed system-wide		Use
Emergency access from any browser	Use
Working with local files and databases		Use

In practice: Cloud Shell is ideal for learning, quick tasks, and emergencies. For daily development and production operations, install gcloud CLI locally for persistent configuration, no time limits, and full system access.

TL;DR

gcloud CLI is the official command-line tool for Google Cloud. Install it locally or use it pre-installed in Cloud Shell.
Authenticate with gcloud auth login (interactive), gcloud auth application-default login (for app code), or service account keys (for CI/CD). Prefer Workload Identity over downloaded keys.
Command structure is gcloud GROUP SUBGROUP ACTION [ARGS] [FLAGS]. Use --help at any level for documentation and examples.
Global flags like --project, --zone, --format, --filter, and --quiet control behavior across all commands.
Named configurations let you switch between projects and accounts without re-authenticating.
Cloud Shell is a free, browser-based Debian VM with gcloud CLI and development tools pre-installed, 5 GB persistent storage, and a 50-hour weekly quota.
Use gcloud CLI locally for daily development and automation. Use Cloud Shell for quick experiments, tutorials, and emergency access.

Resources

Install the Google Cloud CLI Official installation instructions for all platforms.

gcloud CLI Reference Complete command reference for all gcloud CLI commands.

gcloud CLI Cheat Sheet Quick reference for the most common gcloud commands.

Application Default Credentials How ADC works for local development and application libraries.

Cloud Shell Documentation Official documentation for Cloud Shell features and limitations.

gcloud storage vs gsutil Transition guide from legacy gsutil to gcloud storage commands.

Getting Started Signup, free tier, first project setup, and shared responsibility.

Regions and Zones Google Cloud infrastructure hierarchy and how to choose regions.

Creating Your First VM Step-by-step guide with gcloud CLI examples for VM creation.

Lalit's Cloud & DevOps notes