GOOGLE CLOUD · GCLOUD · PRACTICAL CLI

gcloud Commands: A Practical Google Cloud CLI Guide for Engineers

You do not need to memorize hundreds of gcloud commands. What helps is understanding how the CLI is put together, knowing the commands you will use all the time, and knowing how to find the rest when you need them.

Authentication IAM Compute GKE Cloud Run Automation

Learning gcloud commands is easier when you follow a real task. Imagine you need to deploy a Cloud Run service, inspect its permissions, and understand why it is failing. Before choosing a command, you need to know which account is active, which project you are changing, and what result you expect.

Most engineers learn the CLI one copied command at a time. That gets the immediate job done, but it makes the next unfamiliar task harder. This guide connects the pieces: understand command structure, establish your context, work with individual services, and then combine commands into a repeatable workflow.

Read the first four sections in order. After that, use the contents to find the service you need, or jump to the end-to-end Cloud Run example. Use the examples as a repeatable workflow and check command help whenever you need an unfamiliar flag.

Before you start

New to the CLI? Open Cloud Shell for a browser-based terminal with gcloud installed, or follow the local installation guide. On a local installation, run gcloud init to sign in and select a project. Cloud Shell uses your signed-in account; authorize it when prompted.

First five minutes: run gcloud version, gcloud auth list, and gcloud config get-value project. Confirm the active account and project ID before continuing. An unset project means you still need to select one in section 2.

A project groups your resources; a region is a geographic location, and a zone is a deployment area within a region. IAM means Identity and Access Management. An API is the service interface that a command calls.

The examples use Bash syntax; replace uppercase placeholders such as PROJECT_ID and REGION with your own values. Commands that create or deploy resources require appropriate permissions and may incur charges. For your first run, use a test project.

Your reference while you work

The GitHub command reference contains searchable command indexes, a practical cheat sheet, and a regeneration script. The current indexes list command names; use built-in --help or the official CLI reference for descriptions, arguments, and flags. The tutorial stays here on the blog.

For example, combine a command with its purpose and a way to look up the details:

TEXT

gcloud compute instances list
What it does: Lists Compute Engine virtual machine instances.
Usage help: gcloud compute instances list --help

START HERE

First, understand the shape of a gcloud command

A gcloud command usually reads left to right:

BASH

gcloud compute instances list

Think of that as:

TEXT

gcloud
  └── compute
       └── instances
            └── list

gcloud — the CLI
compute — the command group
instances — the resource group
list — the operation

Once you see this pattern, unfamiliar commands become much easier to guess.

For example:

BASH

gcloud run services list
gcloud artifacts repositories list
gcloud secrets versions access
gcloud container clusters describe

These lines illustrate command paths, not a script to run together. For example, accessing a secret needs a version and secret name; describing a cluster needs its name and location. Those arguments appear in the service sections below. Similarly, some-group, some-command, and SOME_COMMAND are placeholders, not actual commands. GA means generally available.

You do not need to remember every command. You need to understand the hierarchy.

Google’s CLI also has GA, beta, and alpha command tracks. A command may appear as:

BASH

gcloud run services list
gcloud beta some-group some-command
gcloud alpha some-group some-command

For production scripts, prefer GA commands unless you deliberately need a beta or alpha feature.

CHECK YOUR CONTEXT

Check the Active Account and Project

A surprising number of CLI mistakes happen because the engineer is using the wrong account or the wrong project.

These are the commands I check first when something feels strange:

BASH

gcloud auth list
gcloud config list
gcloud config get-value project
gcloud config get-value account

To sign in:

BASH

gcloud auth login

For Application Default Credentials used by local application code:

BASH

gcloud auth application-default login

Those are different things. Your gcloud CLI credentials and the credentials your local application uses are related concepts, but they are not interchangeable.

To set a project:

BASH

gcloud config set project PROJECT_ID

To set defaults for region and zone:

BASH

gcloud config set compute/region REGION
gcloud config set compute/zone ZONE

For one-off commands, I often prefer being explicit:

BASH

gcloud compute instances list --project=PROJECT_ID

That is especially useful when you work across several environments.

WORK SAFELY

Use named configurations for Dev, Test and Prod

If you constantly switch between projects, do not keep overwriting one global configuration.

Create separate configurations instead. Creating a configuration activates it by default. After each create command below, set its account with gcloud config set account YOUR_EMAIL, using an account already listed by gcloud auth list, then set its project. Replace YOUR_EMAIL with your own signed-in email. A configuration does not grant access to that project.

These examples finish in prod; before practicing resource-changing commands, switch back with gcloud config configurations activate dev and verify gcloud config list.

BASH

gcloud config configurations create dev
gcloud config set project DEV_PROJECT_ID

gcloud config configurations create prod
gcloud config set project PROD_PROJECT_ID

List them:

BASH

gcloud config configurations list

Switch between them:

BASH

gcloud config configurations activate dev
gcloud config configurations activate prod

Or use one for a single command:

BASH

gcloud --configuration=prod compute instances list

This is one of the simplest ways to reduce accidental cross-environment work.

USE THE CLI

Use the Built-In Command Help

The CLI already knows how to explain itself.

Start here:

BASH

gcloud help

Then narrow down:

BASH

gcloud compute --help
gcloud compute instances --help
gcloud compute instances create --help

That last step matters because flags often change faster than your memory.

If I know the command family but not the exact syntax, I normally use --help before I search anywhere else.

You can also inspect your installed version:

BASH

gcloud version

And general environment information:

BASH

gcloud info

PROJECTS & APIS

Projects and APIs

List projects you can access:

BASH

gcloud projects list

Describe one:

BASH

gcloud projects describe PROJECT_ID

A common setup task is enabling services:

BASH

gcloud services list --available
gcloud services list --enabled
gcloud services enable run.googleapis.com
gcloud services enable artifactregistry.googleapis.com

Disable a service only when you understand the impact:

BASH

gcloud services disable SERVICE_NAME

For scripts, pass the project explicitly when the environment matters:

BASH

gcloud services enable run.googleapis.com --project=PROJECT_ID

IAM

IAM commands you will use often

See a project’s IAM policy:

BASH

gcloud projects get-iam-policy PROJECT_ID

A more readable table:

BASH

gcloud projects get-iam-policy PROJECT_ID \
  --format="table(bindings.role,bindings.members)"

Add a role binding:

BASH

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="user:user@example.com" \
  --role="roles/viewer"

Remove it:

BASH

gcloud projects remove-iam-policy-binding PROJECT_ID \
  --member="user:user@example.com" \
  --role="roles/viewer"

List service accounts:

BASH

gcloud iam service-accounts list

Describe one:

BASH

gcloud iam service-accounts describe SERVICE_ACCOUNT_EMAIL

For production automation, avoid reaching for service-account key files by default. Where your environment supports it, prefer short-lived credentials and service account impersonation.

Impersonation needs the Service Account Credentials API enabled and permission to generate tokens for the target service account, commonly via roles/iam.serviceAccountTokenCreator. The target account also needs permission for the requested operation. See the impersonation setup guide; adding the flag alone does not grant access.

For example:

BASH

gcloud projects describe PROJECT_ID \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

COMPUTE

Compute Engine

List VMs:

BASH

gcloud compute instances list

Describe one:

BASH

gcloud compute instances describe INSTANCE_NAME --zone=ZONE

Create a VM:

BASH

gcloud compute instances create INSTANCE_NAME \
  --zone=ZONE \
  --machine-type=e2-medium

Start and stop:

BASH

gcloud compute instances start INSTANCE_NAME --zone=ZONE
gcloud compute instances stop INSTANCE_NAME --zone=ZONE

SSH:

BASH

gcloud compute ssh INSTANCE_NAME --zone=ZONE

Copy a file:

BASH

gcloud compute scp ./local-file.txt \
  INSTANCE_NAME:~/local-file.txt \
  --zone=ZONE

Networking commands are also under gcloud compute:

BASH

gcloud compute networks list
gcloud compute networks subnets list
gcloud compute firewall-rules list
gcloud compute addresses list
gcloud compute routes list

This is worth remembering because not everything under compute is a VM.

STORAGE

Cloud Storage: use gcloud storage

For current workflows, use the gcloud storage command group.

List buckets:

BASH

gcloud storage buckets list

Create a bucket:

BASH

gcloud storage buckets create gs://BUCKET_NAME \
  --location=REGION

List objects:

BASH

gcloud storage ls gs://BUCKET_NAME

Copy a file:

BASH

gcloud storage cp ./report.csv gs://BUCKET_NAME/

Copy a directory recursively:

BASH

gcloud storage cp --recursive ./data gs://BUCKET_NAME/

Download:

BASH

gcloud storage cp gs://BUCKET_NAME/report.csv .

Remove an object:

BASH

gcloud storage rm gs://BUCKET_NAME/report.csv

CLOUD RUN

Cloud Run

List services:

BASH

gcloud run services list

Deploy from source:

BASH

gcloud run deploy SERVICE_NAME \
  --source=. \
  --region=REGION

Deploy an existing image:

BASH

gcloud run deploy SERVICE_NAME \
  --image=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG \
  --region=REGION

Describe a service:

BASH

gcloud run services describe SERVICE_NAME --region=REGION

Get only the service URL:

BASH

gcloud run services describe SERVICE_NAME \
  --region=REGION \
  --format="value(status.url)"

List revisions:

BASH

gcloud run revisions list \
  --service=SERVICE_NAME \
  --region=REGION

Delete a service:

BASH

gcloud run services delete SERVICE_NAME --region=REGION

GKE

List clusters:

BASH

gcloud container clusters list

Describe a cluster:

BASH

gcloud container clusters describe CLUSTER_NAME \
  --location=LOCATION

Get Kubernetes credentials:

BASH

gcloud container clusters get-credentials CLUSTER_NAME \
  --location=LOCATION

After that, kubectl uses the generated kubeconfig context. On your local machine, install both kubectl and gke-gcloud-auth-plugin using the GKE client setup instructions. LOCATION is the cluster region for a regional cluster or zone for a zonal cluster. You also need permission and network access to the cluster endpoint.

Create a cluster only after checking the current flags for the cluster mode you want:

BASH

gcloud container clusters create --help

GKE evolves quickly, so this is one area where blindly reusing an old command from a blog post is a bad habit.

ARTIFACT REGISTRY

Artifact Registry

List repositories:

BASH

gcloud artifacts repositories list

Create a Docker repository:

BASH

gcloud artifacts repositories create REPOSITORY \
  --repository-format=docker \
  --location=REGION

Configure Docker authentication:

BASH

gcloud auth configure-docker REGION-docker.pkg.dev

List Docker images:

BASH

gcloud artifacts docker images list \
  REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY

CLOUD BUILD

Cloud Build

Run this from a source directory containing a valid cloudbuild.yaml; a bare gcloud builds submit uses that filename by default. It does not invent build steps for an arbitrary folder. Enable the Cloud Build API and ensure the build identity has access to its inputs and outputs. For a Dockerfile build, the command reference explains the alternative --tag option. Submit the configured build:

BASH

gcloud builds submit

Submit with a configuration file:

BASH

gcloud builds submit --config=cloudbuild.yaml

List builds:

BASH

gcloud builds list

Describe a build:

BASH

gcloud builds describe BUILD_ID

Read build logs:

BASH

gcloud builds log BUILD_ID

Before a source-based deployment, it can also be useful to inspect what your .gcloudignore rules will upload:

BASH

gcloud meta list-files-for-upload

SECRETS

Secret Manager

List secrets:

BASH

gcloud secrets list

Create a secret:

BASH

gcloud secrets create SECRET_NAME \
  --replication-policy=automatic

Add a version from stdin using a dummy value for this demonstration. Do not replace secret-value with a real password in a command you type: the command itself can remain in shell history. For real credentials, use a secure input or secret-management workflow:

BASH

printf '%s' 'secret-value' | \
  gcloud secrets versions add SECRET_NAME --data-file=-

Access the latest version:

BASH

gcloud secrets versions access latest \
  --secret=SECRET_NAME

In shell history and CI logs, be careful not to expose secrets just because a command makes it convenient to print them.

CLOUD SQL

Cloud SQL

List instances:

BASH

gcloud sql instances list

Describe an instance:

BASH

gcloud sql instances describe INSTANCE_NAME

List databases:

BASH

gcloud sql databases list --instance=INSTANCE_NAME

List users:

BASH

gcloud sql users list --instance=INSTANCE_NAME

For creating or modifying production databases, check the current command help rather than copying an old set of flags:

BASH

gcloud sql instances create --help

Database defaults and supported flags are exactly the kind of thing you want to verify at execution time.

LOGGING

Logs: one of the most useful gcloud workflows

Read recent logs:

BASH

gcloud logging read \
  'severity>=ERROR' \
  --limit=50

Return JSON:

BASH

gcloud logging read \
  'severity>=ERROR' \
  --limit=50 \
  --format=json

Filter Cloud Run logs:

BASH

gcloud logging read \
  'resource.type="cloud_run_revision"' \
  --limit=50

The exact resource and log filters depend on the service, but gcloud logging read is worth learning because it lets you investigate from a terminal or script without switching to the console.

FILTER & FORMAT

Filter and Format Command Output

This is the part many command lists skip.

A command that returns 500 resources is not very useful until you can narrow and shape the output.

Filter

BASH

gcloud compute instances list \
  --filter="status=RUNNING"

Combine conditions:

BASH

gcloud compute instances list \
  --filter="status=RUNNING AND zone:us-central1"

JSON

BASH

gcloud compute instances list --format=json

Great for scripts and tools such as jq.

Value

BASH

gcloud config get-value project

Or:

BASH

gcloud run services describe SERVICE_NAME \
  --region=REGION \
  --format="value(status.url)"

This is ideal when a shell script needs exactly one value.

Table

BASH

gcloud compute instances list \
  --format="table(name,zone,status)"

CSV

BASH

gcloud compute instances list \
  --format="csv(name,zone,status)"

Once you learn --filter and --format, you stop treating gcloud as a collection of one-off terminal commands and start using it as an automation tool.

AUTOMATION

A safer way to use gcloud in scripts

A few habits make scripts easier to trust.

Be explicit about project and location

BASH

gcloud run services list \
  --project=PROJECT_ID \
  --region=REGION

Use machine-readable output

BASH

gcloud projects describe PROJECT_ID \
  --format=json

Disable prompts when automation requires it

BASH

gcloud run services delete SERVICE_NAME \
  --region=REGION \
  --quiet

Do not add --quiet casually to destructive commands. In automation it is useful; interactively, the confirmation prompt can save you.

Fail early in shell scripts

For Bash:

BASH

set -euo pipefail

Then check the exit status of commands that matter.

Prefer impersonation over permanent key files

Where possible:

BASH

gcloud SOME_COMMAND \
  --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

Short-lived credentials are easier to control than long-lived downloaded keys.

TROUBLESHOOTING

Troubleshooting gcloud itself

When something fails, start simple.

Check the version:

BASH

gcloud version

Check configuration:

BASH

gcloud config list

Check authentication:

BASH

gcloud auth list

Check environment information:

BASH

gcloud info

Increase logging:

BASH

gcloud SOME_COMMAND --verbosity=debug

For HTTP-level troubleshooting:

BASH

gcloud SOME_COMMAND --log-http

Be careful with verbose HTTP logs in shared terminals or CI systems because request and response data may contain information you do not want stored permanently.

PUT IT TOGETHER

A practical example: from terminal to Cloud Run

Here is a small flow that ties several commands together. It assumes you have application source code ready to deploy. If you do not, first create the small app in Google’s Python Hello World quickstart, then return here.

Use a test project with billing enabled. Confirm the source-deployment permissions for both your user and the build service account; enabling APIs alone is not enough. Run the deployment from the app directory: the dot in --source=. means the current folder. Replace SERVICE_NAME with a name such as hello-cli and REGION with your chosen region, such as us-central1.

For a first practice run, keep the service authenticated if prompted. In Cloud Shell, a separate gcloud auth login is normally unnecessary; confirm your account with gcloud auth list. On a local terminal, sign in below.

Sign in

BASH

gcloud auth login

Set the project

BASH

gcloud config set project PROJECT_ID

Confirm it

BASH

gcloud config get-value project

Enable the services you need

BASH

gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable artifactregistry.googleapis.com

Deploy

BASH

gcloud run deploy SERVICE_NAME \
  --source=. \
  --region=REGION

Get the URL

BASH

gcloud run services describe SERVICE_NAME \
  --region=REGION \
  --format="value(status.url)"

Check the service

BASH

gcloud run services describe SERVICE_NAME \
  --region=REGION

Read recent logs if something is wrong

BASH

gcloud logging read \
  'resource.type="cloud_run_revision"' \
  --limit=50

That is the kind of workflow worth learning. You are not memorizing eight isolated commands. You are following the lifecycle of a real task.

Verify the result and clean up

A successful deployment returns a service URL. A private service still requires an authorized caller; use the authenticated invocation instructions if opening it in a browser gives an access error. The log filter above covers all Cloud Run services in the selected project; narrow it to your service when troubleshooting.

When finished, remove only the practice service you created, after checking its name, project and region:

BASH

gcloud run services delete SERVICE_NAME \
  --project=PROJECT_ID \
  --region=REGION

This does not remove stored container images or other build artifacts. Review resources created in the test project and remove only those you no longer need; retained resources can still incur charges.

FULL REFERENCE

What about the complete list of gcloud commands?

A command index is useful when you know what you are looking for. It is less useful as a learning path, especially when the CLI changes between releases.

Use the official Google Cloud CLI reference for current descriptions and syntax. Pair it with gcloud COMMAND --help to check what your installed version supports.

The KloudXpert GitHub companion contains GA, Beta and Alpha command-name indexes, a practical cheat sheet, and a regeneration script. Browse the public GitHub command reference; the tutorial and workflows are here on the blog.

Treat any generated index as a dated snapshot, and verify the flags before running a command against a real environment.

KEEP THESE CLOSE

Frequently Used Commands

These commands cover common account, project, and service checks:

BASH

gcloud auth login
gcloud auth list
gcloud config list
gcloud config set project PROJECT_ID
gcloud config configurations list
gcloud projects list
gcloud services list --enabled
gcloud services enable SERVICE_NAME
gcloud compute instances list
gcloud run services list
gcloud container clusters list
gcloud artifacts repositories list
gcloud secrets list
gcloud logging read FILTER
gcloud info
gcloud version

And one habit:

BASH

gcloud SOME_COMMAND --help

That habit is more useful than memorizing another hundred commands.

WRAP-UP

Final thought

The best way to learn gcloud is not to read a giant command list from top to bottom.

Learn the shape of the CLI. Know which account and project you are using. Get comfortable with --help, --filter, and --format. Then learn commands as real problems give you a reason to use them.

Keep the complete reference nearby for the rest.

Official Google Cloud CLI reference: https://cloud.google.com/sdk/gcloud/reference

Keep the full reference nearby

Start with your account and project, choose the smallest command that answers your question, inspect the result, and then automate the workflow. Keep the official reference open when you need the details.

First, understand the shape of a gcloud command

Check the Active Account and Project

Use named configurations for Dev, Test and Prod

Use the Built-In Command Help

Projects and APIs

IAM commands you will use often

Compute Engine

Cloud Storage: use gcloud storage

Cloud Run

GKE

Artifact Registry

Cloud Build

Secret Manager

Cloud SQL

Logs: one of the most useful gcloud workflows

Filter and Format Command Output

Filter

JSON

Value

Table

CSV

A safer way to use gcloud in scripts

Be explicit about project and location

Use machine-readable output

Disable prompts when automation requires it

Fail early in shell scripts

Prefer impersonation over permanent key files

Troubleshooting gcloud itself

A practical example: from terminal to Cloud Run

Sign in

Set the project

Confirm it

Enable the services you need

Deploy

Get the URL

Check the service

Read recent logs if something is wrong

Verify the result and clean up

What about the complete list of gcloud commands?

Frequently Used Commands

Final thought

Related Posts

Leave a Comment Cancel Reply