← All cheatsheets

Cloud

gcloud CLI — auth, projects, and everyday operations

Authenticate the gcloud CLI, confirm which account and project you are in, switch context safely, and run the everyday list, describe, log-tail, and deploy commands.

Docs-checkedgcpgcloudiamprojectgkerun

Quick reference — reach for these first

Who am I / what contextgcloud config listPrint the active account, project and region before you touch anything — this is the first command of every session.
Authenticate the CLIgcloud auth loginAuthorize gcloud with your Google account in a browser. Add gcloud auth application-default login so client libraries get ADC too.
Set the projectgcloud config set project PROJECT_IDPoint every later command at PROJECT_ID. Confirm with gcloud projects describe PROJECT_ID.
List resourcesgcloud compute instances listEnumerate VMs across zones. Swap the group (run, container, storage, sql) to inventory other services the same way.
Tail logsgcloud logging read '...' --limit 20 --freshness 1hRead recent entries for a resource type. One central read path covers Cloud Run, GKE and Compute Engine.

How gcloud resolves identity, project and region for every command

How gcloud resolves identity, project and region for every commandTwo auth commands produce credentials: gcloud auth login makes user credentials for the gcloud CLI, and gcloud auth application-default login makes Application Default Credentials for client libraries. The active gcloud configuration holds account, project and default region, shown by gcloud config list. Every command reads that configuration to act as one account on one project in one region. Switch context by activating another configuration or passing --project and --region.credentialsgcloud auth loginuser creds → gcloud CLIgcloud auth application-default loginADC → client librariesactive configurationgcloud configaccount = you@…project = PROJECT_IDregion  = REGIONcommandgcloud run deploy …acts as ACCOUNT onPROJECT in REGIONreadsgcloud config list → confirm account + project before any changeswitch: gcloud config configurations activate NAME · or --project / --regionGCP has no "subscription" — the billing link is the billing account (gcloud billing).

Text equivalent: Credentials come from two commands: gcloud auth login creates user credentials used by the gcloud CLI, and gcloud auth application-default login creates Application Default Credentials used by client libraries. The active gcloud configuration holds the account, project and default region, which gcloud config list prints. Every gcloud command reads the active configuration to decide which account acts on which project in which region. Switch context by activating another named configuration or passing per-command flags such as --project and --region. GCP has no subscription; the billing link is the billing account.

Common tasks

Task · Command · What to check

TaskCommandWhat to check
Authenticate the CLI (interactive)gcloud auth loginBrowser completes; gcloud auth list shows your account marked with a '*'.
Set up ADC for local application codegcloud auth application-default loginWrites ~/.config/gcloud/application_default_credentials.json; client libraries now authenticate without a key file.
Confirm the active context (do this first)gcloud config list[core] account and [core] project are the exact identity and project you intend to act on.
Switch the active projectgcloud config set project PROJECT_IDgcloud config get-value project echoes PROJECT_ID.
Switch the active accountgcloud config set account ACCOUNTgcloud auth list marks ACCOUNT active; re-run gcloud auth login if it shows no credentials.
Set a default region / zonegcloud config set compute/region REGIONgcloud config get-value compute/region returns REGION, so region-scoped commands stop prompting.
Keep one named config per environmentgcloud config configurations activate CONFIGgcloud config configurations list shows IS_ACTIVE=True on CONFIG and its bound account+project.
List the projects you can seegcloud projects listPROJECT_ID appears with its project number and display name.
Confirm the billing link (GCP's 'subscription')gcloud billing projects describe PROJECT_IDbillingEnabled: true and billingAccountName matches the expected BILLING_ACCOUNT_ID.
Describe one resource in detailgcloud compute instances describe NAME --zone ZONEReturns status, machineType and network IPs for NAME; confirms you are reading the right object.
Read recent logs for a resourcegcloud logging read 'resource.type="cloud_run_revision"' --limit 20 --freshness 1hEntries stream back newest-first; empty output means wrong filter, wrong project, or no recent traffic.
Get kubeconfig for a GKE clustergcloud container clusters get-credentials CLUSTER --region REGIONkubeconfig updated; kubectl config current-context names gke_PROJECT_ID_REGION_CLUSTER.
Enable a required API (LABEL: changes project config)gcloud services enable run.googleapis.comgcloud services list --enabled lists run.googleapis.com; retry the command that failed with SERVICE_DISABLED.
Deploy a Cloud Run service (LABEL: BILLABLE, creates resources)gcloud run deploy SERVICE --image IMAGE --region REGIONCommand prints a Service URL; gcloud run services list shows SERVICE with a Ready condition.

From zero: authenticate, confirm context, do a safe read, then one scoped change

docs-checked

1
Authenticate the CLI against your Google account.
gcloud auth login
# Opens a browser; on return:
# You are now logged in as [you@example.com].
2
Point the CLI at the target project and default region.
gcloud config set project PROJECT_ID && gcloud config set compute/region REGION
# Updated property [core/project].
# Updated property [compute/region].
✓
CONFIRM the active context BEFORE any change — account and project must be the intended ones.
gcloud config list
# [compute]
# region = REGION
# [core]
# account = you@example.com
# project = PROJECT_ID
4
Confirm the billing link (GCP's closest thing to a 'subscription').
gcloud billing projects describe PROJECT_ID
# billingAccountName: billingAccounts/BILLING_ACCOUNT_ID
# billingEnabled: true
5
Safe read: list resources to see current state and prove access — changes nothing.
gcloud compute instances list
# NAME   ZONE       STATUS
# web-1  REGION-a   RUNNING
6
Small scoped action — enable one API. Reversible and creates no billable resources yet. LABEL: changes project config.
gcloud services enable run.googleapis.com
# Operation finished successfully.
✓
Verify the action took effect.
gcloud services list --enabled --filter='config.name:run.googleapis.com'
# NAME                TITLE
# run.googleapis.com  Cloud Run Admin API
!
Rollback note: only disable what you added, and only if nothing depends on it — gcloud services disable run.googleapis.com --force can break dependent resources.

Troubleshooting — symptom → first check → next check

SymptomFirst checkEstablishesNext check
PERMISSION_DENIED / 403 on a commandgcloud config listWhether the active account and project are the ones that actually hold the needed role (most 403s are wrong-context, not missing-role).gcloud projects get-iam-policy PROJECT_ID — confirm the account has the role; grant with gcloud projects add-iam-policy-binding.
Reauthentication required / invalid_grant / credentials have expiredgcloud auth listWhether the account still has a live token or was revoked, expired, or never credentialed.Re-run gcloud auth login; for client-library errors also run gcloud auth application-default login.
Change landed on the wrong project or accountgcloud config configurations listWhich named configuration (and therefore which account+project) was active when the command ran.gcloud config configurations activate CONFIG, or set project/account explicitly, then re-run with --project to be certain.
Required argument --region / --zone not specifiedgcloud config get-value compute/regionWhether any default region or zone is configured for region-scoped commands.gcloud config set compute/region REGION (and run/region for Cloud Run), or pass --region / --zone per command.
Quota exceeded / RESOURCE_EXHAUSTED / HTTP 429Re-run the command with --log-http and read the 429 response bodyWhich limit is being hit — a per-minute API rate limit versus a hard resource quota.Back off and retry for rate limits; for resource quotas open IAM & Admin > Quotas and request an increase.
API [x] has not been used / SERVICE_DISABLEDgcloud services list --enabledWhether the required API is enabled on this project at all.gcloud services enable SERVICE.googleapis.com, then retry the original command.
The billing account for project is not found / FAILED_PRECONDITION on creategcloud billing projects describe PROJECT_IDWhether a billing account is linked and enabled for the project.Link one: gcloud billing projects link PROJECT_ID --billing-account BILLING_ACCOUNT_ID (needs Billing Account User).

References

Google Cloud CLI (gcloud) 500+ on macOS or Linux; commands target a single GCP project you hold IAM access to. GCP has no "subscription" — the closest link is the billing account.

Related sheets