Guide to Installing and Testing the Google Cloud CLI (gcloud)

The Google Cloud CLI (gcloud) is part of the Google Cloud SDK, allowing you to manage Google Cloud Platform (GCP) resources from the command line. This guide covers installation and testing on Linux (including Windows/WSL2) and macOS systems, ensuring you can get up and running quickly.

Security Warning: GCP CLI usage from outside of the GCP infrastructure stores credentials on your local machine, this means that if your machine is compromised, the damage could be significant. To minimize the risk, please ensure you understand the security implications and only continue if you are comfortable with the security risks involved.

$ sudo snap install google-cloud-cli --classic

$ gcloud --version

$ sudo snap install google-cloud-cli --classic

$ gcloud --version

$ gcloud --version

Before configuring the gcloud CLI, you will have a decision to make about how to authenticate/authorize the CLI to access your GCP resources.

Using Your Same GCP Web Interface Account

• Pros:
  Convenience: If you’re already using this account (e.g., your personal Google account or a work email tied to GCP), it’s straightforward to authenticate with gcloud init via browser login. No extra setup needed.

  Consistency: Your web console and CLI experience align—same permissions, same project access.

  Expiring Credentials - if configured correctly: If you use the web interface account for CLI access, the credentials will expire after a period of time, this is a security feature and is designed to force users to regularly re-authenticate.

• Cons:
  Security Risk: If this account has broad permissions (e.g., Owner role), using it for CLI increases exposure, especially if your machine is compromised or you accidentally run a destructive command.

Using an Explicit Account for the CLI

• Pros:
  Security: A dedicated service account with narrowly scoped permissions (e.g., only Compute Admin or Storage Viewer) limits what the CLI can do, reducing risk.

  Automation-Friendly: Service accounts with key files (e.g., JSON keys) are ideal for scripts or CI/CD, and setting this up early with gcloud init prepares you for that.

  Separation of Concerns: A CLI-specific account can be distinct from your web console account, making it easier to audit or revoke access if needed.

• Cons:

  Setup Overhead: You’ll need to create the account, assign roles, generate a key (for service accounts), and configure it with gcloud auth activate-service-account or gcloud init.

  Non-expiring credentials If you use the service account for CLI access, the credentials will not expire (at least not without significantly more complex configuration), this is a security risk.

Recommendation

For general management of services, a regular user account is recommended due to the expiring credentials, however you should however ensure that expiring credentials are correctly configured. This is covered in this guide, on the next page.

For automated processes a service account may be more appropriate. You should however ensure that these accounts are configured to only allow the actions required by the automation and always remember that if the account is compromised, all of these actions could be performed by the attacker without the need for any additional authentication.

Using Your Regular User Account for Sign-In

Important Check

Before continuing, ensure that a session expiry time is configured. If your Cloud organization was created before 2023 there is a significantly higher chance there is not a session expiry time configured which would mean the credentials never expire.

• Sign into https://admin.google.com with an administrative account.

• Navigate to Security > Access and data control > Google Cloud session control

• Select the organizational unit if you have more than one.

• Ensure Require reauthentication is checked.

• Ensure a suitable value is set Reauthentication frequency. It is not recommended to set this value any higher than would cover a working day.

• Click Save/Override if you have changed any values.

Configure the CLI

To initialize the gcloud CLI and set it up for use, type:

$ gcloud init

If you have an existing configuration you'll be given the option to re-initialize or create a new one, if this is the first time the command has been ran it will jump straight into the setup prompts.

You will be asked to sign in using a web browser, if supported this will open up automatically, if not, just copy and paste the full URL given to complete the sign-in process.

The actual sign-in process will vary depending on whether you have previously accessed your account via the browser, just ensure you select or log into the correct account if you have multiple.

You will be asked to share your account details with Google Cloud SDK which you will need to agree to in order to use the CLI.

Once completed you will be presented with a You are now authenticated with the cloud CLI web page.

Return to your terminal window. If you have multiple projects, you'll be presented with:

• Pick cloud project to use

Along with a list of projects so just select the one you'll be using with the CLI. You can set gcloud up for additional projects later if you need to.

Note: It is possible you will see projects that you don't immediately recognize, these may be projects you have been added to or projects tied to other Google services and data APIs which you have access to via your account or Google Workspace.

If you don't have a default zone already set, you'll be prompted:

• Do you want to configure a default Compute Region and Zone? (Y/n)

Setting a default region may save a bit of typing later, so I'd suggest saying yes and selecting a region close to you or one you know you'll regularly be using.

That's it for the configuration. Your first configuration will be the default and you can run the same gcloud init command to manage other projects if you wish.

Let's try a few command to ensure everything is working:

$ gcloud config list

This should return a list of the current configuration settings, something like this:

[compute]
region = us-central1
[core]
account = [email protected]
project = my-test-project

And to list our compute instances (if we have appropriate permissions):

$ gcloud compute instances list

If you have instances in multiple regions and zones you should see them all listed. The majority of list commands will return results across all regions and zones however that should not be assumed to always be the case, you should always check the documentation which you can do by adding --help to the end of the command, eg:

$ gcloud compute instances list --help

You will see from the documentation above we can also restrict the results to a specific zone by adding the --zone flag, eg:

$ gcloud compute instances list --zones us-central1-c

This completes the setup and testing. You only need to continue to the next page if you also need to set up a service account for the CLI.

Using a New Service Account for the CLI

If you have successfully completed the steps on the previous page to use your regular user account for sign-in, you can skip this section unless you have a specific reason to use a service account.

Important: The instructions below configure a service account with long-term credentials, this comes with significant security risks, please ensure you understand the security implications, ensure only needed permissions are granted and always remember that if the account is compromised, all of these actions could be performed by the attacker without the need for any additional authentication.

1. Create the Service Account in the Web Interface

Use the Google Cloud Console to set up the service account.

• Access the Console:

  • Go to console.cloud.google.com
  • Select your project from the top dropdown if not already selected (e.g., my-project-id).

• Navigate to Service Accounts:

  • In the left sidebar, click IAM & Admin > Service Accounts.

• Create the Service Account:

  • Click + Create Service Account.
  • Service account name: Enter gcloud-cli-bot (or your choice).
  • Service account ID: Auto-fills (e.g., gcloud-cli-bot), edit if needed.
  • Description: It is recommended to add an accurate description of the account and its purpose, this well help you identify it in the future as it's always a good idea to keep a check on what accounts are still needed and ensure unneeded ones are disabled or removed, or the very least the key is removed.
  • Click Create and Continue.

• Assign a Role:
  Remember you will be creating long term credentials which won't require any re-authentication so ensure you only grant the minimum permissions required.

  • In Grant this service account access to project, select a role or roles (If you are just here to learn the process, I suggest just selecting Compute Engine -> Compute Viewer for now).
  • Click Continue.

• Skip Optional Steps:

  • Leave Grant users access to this service account blank.
  • Click Done.

• Note the Email:

  • On the Service Accounts list, find your new account (e.g., [email protected]).

2. Generate a Key File for our Service Account

• Open the Service Account:

  • Click on the newly created service account name (e.g., [email protected]).

• Add a Key:

  • Go to the Keys tab.
  • Click Add Key > Create new key.
  • Choose JSON and click Create.
  • The file (e.g., my-project-id-abc123.json) downloads automatically.

Remember: this key file is all that is needed to obtain the access specified by the service account, it should be stored in a secure location and never shared.

• Secure the Key:

  • Rename the file to be gcloud-cli-key.json and move it into your home directory if it has not been saved there (e.g., ~/gcloud-cli-key.json).
    Note: If you are using Windows/WSL and have downloaded the file using a Windows browser, you'll find your home directory in Linux -> Ubuntu -> users -> your-username in the windows file explorer with a default setup.

  • In your terminal type:

    $ chmod 600 ~/gcloud-cli-key.json

    If you get a message saying the file cannot be found, ensure you have copied it to the correct location.
    The chmod command will prevent other users from accessing the key file however it will still be readable to superusers.

3. Configure gcloud CLI with the Service Account

At the command prompt:

• Activate the Service Account:

  • Use the downloaded key file and service account email to activate the account (you can check the email address in the web interface if needed).

    $ gcloud auth activate-service-account [email protected] \
      --key-file ~/gcloud-cli-key.json

• Set the Project:

  • Replace my-project-id with your project ID.

    $ gcloud config set project my-project-id

    Depending on API settings and service account permissions, you may get a warning about API access, you can just ignore this as we don't need to query other projects.

  • Enter 'y' to continue.

• Verify Configuration:

  • Check the active account:

    $ gcloud auth list

    Look for the starred (*) entry matching [email protected].
  • Confirm the project:

    $ gcloud config list project

4. Test the Setup

Run a command to ensure it works. If you have have given access to the Compute Engine -> Compute Viewer role (or an alternative role that gives equivalent access) you should be able to list your compute instances:

• List Resources:

$ gcloud compute instances list

If you have instances in multiple regions and zones you should see them all listed. The majority of list commands will return results across all regions and zones however that should not be assumed to always be the case, you should always check the documentation which you can do by adding --help to the end of the command, eg:

$ gcloud compute instances list --help

You will see from the documentation above we can also restrict the results to a specific zone by adding the --zone flag, eg:

$ gcloud compute instances list --zones us-central1-c

This completes the setup and testing. If you have followed this guide simply to try out the CLI, remember to delete the service account. You can do so in the web GUI by navigating to IAM & Admin -> Service Accounts and selecting Delete in the actions column for the account.