🔧 The Google Cloud CLI (gcloud): Sign In, Configurations, Format and Filter

How gcloud is organized, the sign-in options, named configurations for switching between projects, the --format and --filter flags that replace queries, and the topic guides that work offline

What gcloud is

gcloud is the Google Cloud command-line interface. Its commands are organized as groups, then verbs, and are usually quite readable: gcloud compute instances list, gcloud projects create, gcloud storage buckets create, gcloud config set project. Most things you do are about a project (see the account page): the CLI remembers which one in its configuration.

Getting it

Google offers a package for the usual Linux package managers, a snap, and a tarball that unpacks to a folder and has its own installer. I used the tarball, so that it all lives in one directory that I can delete:

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
tar xzf google-cloud-cli-linux-x86_64.tar.gz
./google-cloud-sdk/install.sh --quiet --path-update=false

Or skip installing: Cloud Shell in the console has gcloud ready and signed in. The version and parts, as run:

user@lab:~$ gcloud --version
Google Cloud SDK 588.0.0
bq 2.1.39
bundled-python3-unix 3.14.7
core 2026.10.02
gcloud-crc32c 1.0.0
gsutil 5.37
user@lab:~$ gcloud config list
[core]
disable_prompts = 1
disable_usage_reporting = true

Your active configuration is: [default]
user@lab:~$ gcloud auth list

No credentialed accounts.

To login, run:
  $ gcloud auth login `ACCOUNT`
user@lab:~$ gcloud compute instances list
ERROR: (gcloud.compute.instances.list) You do not currently have an active account selected.
Please run:

  $ gcloud auth login

to obtain new credentials.

If you have already logged in with a different account, run:

  $ gcloud config set account ACCOUNT

to select an already authenticated account to use.

Before you sign in

The output above also shows an unsigned gcloud:

• gcloud config list shows only the [core] settings, and "Your active configuration is: [default]". (The two disable_ lines are the settings I used to keep the test private.)
• gcloud auth list says "No credentialed accounts." and tells you to run gcloud auth login.
• gcloud compute instances list fails with "You do not currently have an active account selected.", with the two ways out: gcloud auth login, or gcloud config set account ACCOUNT.

Signing in

From Google's documentation (read on 6 October 2026):

• gcloud init is the guided start: it walks you through signing in, and sets up a configuration with an account and a default project.
• gcloud auth login signs in with a user account in the browser, and stores the credentials locally. Google's warning: anyone with access to your files can use the stored credentials, so keep the machine yours.
• gcloud auth application-default login is a separate sign-in for programs you write that use Google's client libraries (Application Default Credentials): it does not change the CLI's own login.
• A service account attached to the machine. On a Compute Engine VM or another Google service, the code finds the service account's credentials by itself.
• Service account keys (a downloaded file) are possible but actively discouraged: Google points to Workload Identity Federation, which gives short-lived tokens and better audit trails.

gcloud auth list shows who is signed in (the active account has an asterisk), and gcloud config list shows the project and the defaults. Run both before you create anything.

Configurations: one tool, several projects

A configuration is a named bundle of settings: account, project, default region and zone. You can have several, and switch between them in one command. This is gcloud's best feature for people who work with more than one project, and it ran for real:

user@lab:~$ gcloud config set project my-lab-4821
Updated property [core/project].
user@lab:~$ gcloud config set compute/region us-central1
ERROR: (gcloud.config.set) You do not currently have an active account selected.
Please run:

  $ gcloud auth login

to obtain new credentials.

If you have already logged in with a different account, run:

  $ gcloud config set account ACCOUNT

to select an already authenticated account to use.
user@lab:~$ gcloud config list
[core]
disable_prompts = 1
disable_usage_reporting = true

Your active configuration is: [default]
user@lab:~$ gcloud config list --format='value(core.project)'
my-lab-4821
user@lab:~$ gcloud config get project
my-lab-4821
user@lab:~$ gcloud config list --format=json
{
  "core": {
    "disable_prompts": "1",
    "disable_usage_reporting": "true",
    "project": "my-lab-4821"
  }
}

Read it:

• gcloud config set project my-lab-4821 worked even though no one was signed in, and gcloud config list now shows project = my-lab-4821. (The project ID is not validated against Google yet.)
• gcloud config set compute/region us-central1 failed, with the same "no active account" error: setting a region or a zone needs a signed-in account, because gcloud checks it against the service. (Remember that when a default-region command fails on a fresh install.)
• --format='value(core.project)' printed just the value, my-lab-4821, with nothing else: the way to use a setting in a script. gcloud config get project does the same job, and --format=json shows the whole configuration as JSON.

Now two configurations:

user@lab:~$ gcloud config configurations list
NAME     IS_ACTIVE  ACCOUNT  PROJECT      COMPUTE_DEFAULT_ZONE  COMPUTE_DEFAULT_REGION
default  True                my-lab-4821
user@lab:~$ gcloud config configurations create work
Created [work].
Activated [work].
user@lab:~$ gcloud config set project other-proj-1234
Updated property [core/project].
user@lab:~$ gcloud config configurations activate default; gcloud config get project
Activated [default].
my-lab-4821

• gcloud config configurations list shows each configuration with its IS_ACTIVE flag, account, project and default zone and region.
• gcloud config configurations create work made and activated a new, empty one. Setting project other-proj-1234 there changed only that one.
• gcloud config configurations activate default switched back, and gcloud config get project confirmed the first project.

On disk (from the same session): the settings are in plain files under ~/.config/gcloud/configurations/, named config_default and config_work, and the file active_config names the one in use. Other files in that folder, such as credentials.db, hold sign-in secrets: back them up carefully or not at all.

The environment variable CLOUDSDK_ACTIVE_CONFIG_NAME=NAME picks the active configuration for one shell (it is named in the offline gcloud topic configurations guide), and CLOUDSDK_CONFIG moves the whole settings folder (it is how this test was kept private).

Flags override the configuration for one command: --project PROJECT_ID, --configuration NAME, --account ACCOUNT (all are in the real help text). In scripts, always pass --project instead of trusting whatever is active.

Format and filter: gcloud's own query language

gcloud does not use JMESPath. It has its own pair of flags (explained in the offline gcloud topic formats and gcloud topic filters guides):

• --format=NAME[ATTRIBUTES](PROJECTION) controls the output. Names: json, yaml, table, value, csv, text and others. With projections you pick fields: for example --format="table(name, zone.basename(), status)".
• --filter=EXPRESSION chooses which resources to list: --filter="status=RUNNING" or --filter="name~^web".
• --limit and --sort-by shorten and order the list.

The real help says: "Use the --format flag to change the default output format of a command", and "Use the --filter flag to select resources to be listed". On a real project (from the documentation, not run here):

gcloud compute instances list
gcloud compute instances list --filter="status=RUNNING" --format="table(name, zone.basename(), machineType.basename(), status)"
gcloud compute instances list --format="value(name)"
gcloud projects list --format=json

• value(name) prints one name per line, ready for a loop.
• zone.basename() trims a long URL to the last part (the zone's name).
• --format=json shows the whole resource, which is how you find out what fields you can select.

Help, with no account

Everything here ran for real and needs no sign-in:

• gcloud help and gcloud COMMAND --help: for example gcloud compute instances create --help, which starts with the synopsis and every flag.
• Topics: gcloud topic lists them, and gcloud topic formats and gcloud topic filters are the two to read first.
• gcloud components list shows the pieces of the CLI (and gcloud components update updates them), for the tarball install: when the CLI comes from a system package manager, updates go through the package manager instead (from the documentation, not run here).
• Release tracks: gcloud beta ... and gcloud alpha ... run commands that are still in preview.

Habits that save you

• gcloud config list and gcloud auth list first. Wrong project is the usual mistake.
• One configuration per project or per job, with names that mean something (personal, client-a).
• In scripts: --project, --quiet (no prompts), and --format=value(...). Do not rely on the active configuration.
• Enable an API before using it: gcloud services enable compute.googleapis.com (a first-day error says an API "has not been used in project"). From the documentation, not run here.
• Use --async on slow operations, and check later.
• No service account key files. Attach a service account to the machine.
• Delete by project when you finish an experiment: gcloud projects delete PROJECT_ID (30 days to restore).

The cheat sheet

• Shape: gcloud GROUP [SUBGROUP] VERB --flag. Help: --help, gcloud topic formats, gcloud topic filters.
• Not signed in: "No credentialed accounts" / "You do not currently have an active account selected". Sign in: gcloud init, gcloud auth login. For code: gcloud auth application-default login. No key files.
• Where am I: gcloud auth list, gcloud config list, gcloud config get project.
• Settings: gcloud config set project ID (works unsigned), gcloud config set compute/region R and compute/zone Z (need an account).
• Configurations: gcloud config configurations list|create NAME|activate NAME. Per command: --project, --configuration, --account.
• Output: --format=json|yaml|table(...)|value(...), --filter="...", --limit, --sort-by. (Not JMESPath.)
• Files: ~/.config/gcloud/configurations/config_NAME, active_config. Env: CLOUDSDK_CONFIG moves the whole folder.

← The AWS CLI (aws): Sign In, Profiles, Output and Query · ↑ All tutorials · The Oracle Cloud CLI (oci): Config File, API Keys, Sessions and Query →