What it is
The Google Cloud CLI (gcloud) is a command-line tool for interacting with Google Cloud Platform services, enabling you to manage resources, deploy applications, and automate tasks.
Installation
Linux
# Download the latest archive
wget https://dl.google.com/dl/cloud/sdk/google-cloud-sdk-461.0.0-linux-x86_64.tar.gz
# Extract the archive
tar -xzf google-cloud-sdk-461.0.0-linux-x86_64.tar.gz
# Run the install script
./google-cloud-sdk/install.sh
Follow the on-screen prompts. It will ask if you want to initialize the SDK and add it to your PATH.
macOS
# Download the latest archive
curl https://dl.google.com/dl/cloud/sdk/google-cloud-sdk-461.0.0-darwin-x86_64.tar.gz --output google-cloud-sdk.tar.gz
# Extract the archive
tar -xzf google-cloud-sdk.tar.gz
# Run the install script
./google-cloud-sdk/install.sh
Follow the on-screen prompts. It will ask if you want to initialize the SDK and add it to your PATH.
Windows
Download the installer from the official Google Cloud SDK documentation: https://cloud.google.com/sdk/docs/install Run the downloaded executable and follow the installation wizard.
Core Concepts
Projects
Google Cloud resources are organized within projects. You’ll often need to specify the project ID when interacting with services.
Regions and Zones
Google Cloud resources are deployed in specific geographic locations.
- Regions: Broad geographic areas (e.g.,
us-central1). - Zones: Isolated locations within a region (e.g.,
us-central1-a).
Components
The gcloud CLI is modular. You can install and update specific components (like kubectl for GKE) as needed.
Commands / Usage
Initialization and Configuration
Initialize the SDK
gcloud init
Guides you through authenticating with your Google Cloud account and setting a default project and region.
Authenticate
gcloud auth login
Logs you into your Google Cloud account via your web browser.
gcloud auth application-default login
Logs you in for Application Default Credentials (ADC), used by many Google Cloud client libraries.
Set Default Project
gcloud config set project my-gcp-project-id
Sets the default project for subsequent gcloud commands.
Set Default Region
gcloud config set compute/region us-central1
Sets the default region for Compute Engine and other regional resources.
Set Default Zone
gcloud config set compute/zone us-central1-a
Sets the default zone for Compute Engine and other zonal resources.
List Configurations
gcloud config list
Displays your current gcloud configuration settings.
List Projects
gcloud projects list
Lists all Google Cloud projects you have access to.
Compute Engine (VMs)
List Instances
gcloud compute instances list
Lists all Compute Engine virtual machine instances in your default project and zone.
List Instances in a Specific Zone
gcloud compute instances list --zone us-east1-b
Lists VM instances in the us-east1-b zone.
Create an Instance
gcloud compute instances create my-vm-instance \
--zone us-central1-a \
--machine-type n1-standard-1 \
--image-project ubuntu-os-cloud \
--image-family ubuntu-2004-lts
Creates a new VM instance named my-vm-instance in us-central1-a with specified machine type and OS image.
SSH into an Instance
gcloud compute ssh my-vm-instance --zone us-central1-a
Establishes an SSH connection to the specified VM instance.
Stop an Instance
gcloud compute instances stop my-vm-instance --zone us-central1-a
Stops a running VM instance.
Start an Instance
gcloud compute instances start my-vm-instance --zone us-central1-a
Starts a stopped VM instance.
Delete an Instance
gcloud compute instances delete my-vm-instance --zone us-central1-a
Deletes a VM instance.
List Machine Types
gcloud compute machine-types list --zone us-central1-a
Lists available machine types in a specific zone.
List Images
gcloud compute images list --project ubuntu-os-cloud
Lists available OS images from a specific project.
Google Kubernetes Engine (GKE)
List Clusters
gcloud container clusters list
Lists all GKE clusters in your project.
Create a Cluster
gcloud container clusters create my-gke-cluster \
--zone us-central1-a \
--num-nodes 3 \
--machine-type n1-standard-2
Creates a GKE cluster named my-gke-cluster with 3 nodes of type n1-standard-2 in us-central1-a.
Get Cluster Credentials
gcloud container clusters get-credentials my-gke-cluster --zone us-central1-a
Configures kubectl to connect to the specified GKE cluster.
Delete a Cluster
gcloud container clusters delete my-gke-cluster --zone us-central1-a
Deletes a GKE cluster.
Cloud Storage (GCS)
List Buckets
gcloud storage buckets list
Lists all GCS buckets in your project.
Create a Bucket
gcloud storage buckets create gs://my-unique-bucket-name --location us-central1
Creates a new GCS bucket named my-unique-bucket-name in the us-central1 region.
Copy Files to a Bucket
gcloud storage cp local-file.txt gs://my-bucket/remote-file.txt
Copies a local file to a GCS bucket.
Copy Files from a Bucket
gcloud storage cp gs://my-bucket/remote-file.txt local-file.txt
Copies a file from a GCS bucket to your local machine.
Sync Directories
gcloud storage rsync local-directory/ gs://my-bucket/remote-directory/
Recursively copies files from a local directory to a GCS bucket, only transferring changed files.
List Objects in a Bucket
gcloud storage ls gs://my-bucket/
Lists all objects (files and directories) within a GCS bucket.
Delete an Object
gcloud storage rm gs://my-bucket/path/to/file.txt
Deletes a specific object from a GCS bucket.
Delete a Bucket
gcloud storage buckets delete gs://my-bucket-name
Deletes an empty GCS bucket.
Cloud Run
List Services
gcloud run services list
Lists all Cloud Run services in your project.
Deploy a Service
gcloud run deploy my-cloud-run-service \
--image gcr.io/my-project/my-image:latest \
--platform managed \
--region us-central1 \
--allow-unauthenticated
Deploys a new or updates an existing Cloud Run service with the specified container image. --allow-unauthenticated makes it publicly accessible.
Invoke a Service
gcloud run services describe my-cloud-run-service --platform managed --region us-central1 --format='value(status.url)'
Gets the URL of a Cloud Run service, which can then be used to invoke it via curl or a browser.
Delete a Service
gcloud run services delete my-cloud-run-service --platform managed --region us-central1
Deletes a Cloud Run service.
Cloud Functions
List Functions
gcloud functions list
Lists all Cloud Functions in your project.
Deploy a Function
gcloud functions deploy my-function \
--runtime nodejs16 \
--trigger-http \
--allow-unauthenticated \
--source .
Deploys a new or updates an existing Cloud Function. --trigger-http sets an HTTP trigger, --allow-unauthenticated makes it publicly invokable, --source . uploads code from the current directory.
Invoke a Function
gcloud functions call my-function
Invokes an HTTP-triggered Cloud Function.
Delete a Function
gcloud functions delete my-function
Deletes a Cloud Function.
App Engine
List Versions
gcloud app versions list
Lists all deployed versions of your App Engine application.
Deploy Application
gcloud app deploy app.yaml
Deploys your App Engine application using the configuration specified in app.yaml.
View Logs
gcloud app logs read
Reads application logs from App Engine.
Delete Application
gcloud app services delete default
Deletes the default App Engine service.
IAM (Identity and Access Management)
List Service Accounts
gcloud iam service-accounts list
Lists all service accounts in your project.
Create a Service Account
gcloud iam service-accounts create my-service-account --display-name "My Custom Service Account"
Creates a new service account.
Grant Role to a Member
gcloud projects add-iam-policy-binding my-gcp-project-id \
--member serviceAccount:my-service-account@my-gcp-project-id.iam.gserviceaccount.com \
--role roles/storage.objectViewer
Grants the roles/storage.objectViewer role to a service account on the project.
List Roles for a Member
gcloud projects get-iam-policy my-gcp-project-id
Retrieves the IAM policy for the project, showing all roles and members.
Deployment Manager
List Deployments
gcloud deployment-manager deployments list
Lists all deployments managed by Deployment Manager.
Create a Deployment
gcloud deployment-manager deployments create my-deployment --config vm-template.yaml
Creates a deployment from a configuration file (vm-template.yaml).
Delete a Deployment
gcloud deployment-manager deployments delete my-deployment
Deletes a deployment and all its resources.
Other Useful Commands
List Components
gcloud components list
Lists installed gcloud CLI components.
Update Components
gcloud components update
Updates all installed gcloud CLI components to the latest version.
Install a Component
gcloud components install kubectl
Installs the kubectl component for managing Kubernetes clusters.
Describe a Resource
gcloud compute instances describe my-vm-instance --zone us-central1-a
Provides detailed information about a specific resource.
List All Resources of a Type
gcloud compute instances list --filter="name~'webserver'"
Lists all resources of a type that match a filter.
Get Help
gcloud help compute instances
Displays detailed help for a specific command or resource.
Common Patterns
Deploying a static website to Cloud Storage
# Create a bucket
gcloud storage buckets create gs://my-static-website-bucket --default-storage-class=STANDARD --location=US
# Upload website files
gcloud storage cp -r ./website-files/* gs://my-static-website-bucket/
# Configure website for index.html and 404.html
gcloud storage buckets update gs://my-static-website-bucket/ --web-main-page-suffix=index.html --web-error-page=404.html
# Make bucket publicly readable (for static websites)
gcloud storage buckets add-iam-policy-binding gs://my-static-website-bucket/ \
--member=allUsers \
--role=roles/storage.objectViewer
Copying logs from a VM to local machine
gcloud compute scp my-vm-instance:/var/log/syslog ./syslog.log --zone us-central1-a
Executing a command on a remote VM
gcloud compute ssh my-vm-instance --zone us-central1-a --command "sudo systemctl restart nginx"
Syncing a local directory to a GCS bucket for backups
gcloud storage rsync ./my-important-data/ gs://my-backup-bucket/my-data-backup/
Getting the URL of a Cloud Run service
RUN_URL=$(gcloud run services describe my-cloud-run-service --platform managed --region us-central1 --format='value(status.url)')
curl $RUN_URL
Creating a GKE cluster and configuring kubectl automatically
gcloud container clusters create my-app-cluster --num-nodes 2 --zone us-central1-a
gcloud container clusters get-credentials my-app-cluster --zone us-central1-a
kubectl get nodes
Gotchas
Default Project and Zone/Region
Commands often default to your configured project and zone/region. If you’re working across multiple projects or regions, explicitly use --project, --region, or --zone flags to avoid applying changes to the wrong environment.
Permissions
gcloud commands will fail if your authenticated user or service account lacks the necessary IAM permissions for the requested operation. Use gcloud iam list-grantable-roles and gcloud projects get-iam-policy to diagnose.
Resource Naming
Some resource names must be globally unique (e.g., GCS bucket names). Others must be unique within a project or region. Pay attention to documentation for specific resource naming constraints.
--format Flag
The --format flag is powerful for scripting. Common formats include json, yaml, text, and value(<field_name>). If a command doesn’t return what you expect, check its output with --format=json to understand its structure.
gcloud storage vs gsutil
gcloud storage is the newer, recommended command-line interface for Cloud Storage. While gsutil still works, gcloud storage is integrated more tightly with the rest of the gcloud CLI. For new scripts, prefer gcloud storage.
Component Updates
Always keep your gcloud CLI updated (gcloud components update) as Google Cloud services and APIs evolve rapidly. Older versions may not support newer features or may encounter unexpected behavior.
Interactive Prompts
Many gcloud commands will prompt for confirmation before destructive actions (like deleting resources). When scripting, use the --quiet or -q flag to suppress these prompts, but be extremely careful as this bypasses confirmation.