gcloud-setup

name	gcloud-setup
description	Install and authenticate the Google Cloud CLI (gcloud, gsutil, bq) on macOS. Use when the user needs to set up gcloud from scratch, re-authenticate, add OAuth scopes for a specific Google API (Search Console, Drive, Sheets, etc.), or fix Application Default Credentials (ADC) issues.
author	Greg Z.
author_email	[e-mail]
author_url	https://www.linkedin.com/in/gregzem/

gcloud Setup & Authentication

This skill is the canonical setup path for gcloud on macOS. It uses only commands verified to work — no guessing, no deprecated flags.

When to use this skill

• gcloud, gsutil, or bq is not installed.
• A Google API call returns PERMISSION_DENIED due to missing scopes or quota project.
• ADC (Application Default Credentials) needs to be (re)created with custom scopes for a non-default Google API.
• User says something like "set up gcloud", "authenticate to Google Cloud", "fix ADC", "add webmasters/drive/sheets scope".

Key facts (memorize — these were the gotchas)

1. The Homebrew cask is gcloud-cli, NOT google-cloud-sdk (the old name is deprecated).
2. gcloud auth login does NOT accept --scopes. For custom scopes use gcloud auth application-default login --scopes=....
3. application-default login REQUIRES cloud-platform in the scope list, even if the target API doesn't need it. Omitting it produces: https://www.googleapis.com/auth/cloud-platform scope is required but not requested.
4. All scope boxes must be checked on the Google consent screen. If the user unchecks cloud-platform, the login succeeds but ADC is unusable: scope is required but not consented.
5. User OAuth credentials need a quota project on API calls via the x-goog-user-project header. Without it: accessNotConfigured / SERVICE_DISABLED.
6. Two different token commands exist. gcloud auth print-access-token returns the token for the user-login (fixed gcloud scopes). gcloud auth application-default print-access-token returns the ADC token (custom scopes). For calling third-party Google APIs with custom scopes, always use the ADC token.

Step 1: Install

# Check first
which gcloud gsutil bq

# If missing, install via Homebrew cask
brew install --cask gcloud-cli

# Verify
gcloud --version
bq version
gsutil version

Python note: the cask bundles a venv; if it warns about Python 3.9, fix with:

brew install python@3.12
export CLOUDSDK_PYTHON="$(brew --prefix)/opt/python@3.12/bin/python3.12"
gcloud components reinstall

Step 2: User login (for running gcloud commands)

gcloud auth login

This opens a browser. The resulting credentials are used by gcloud CLI commands (project management, resource listing, etc.) but do NOT carry custom API scopes — they only have the fixed gcloud default scopes.

Step 3: Pick a project and enable the API you need

# See projects
gcloud projects list

# Set the default
gcloud config set project YOUR_PROJECT_ID

# Enable the API(s) you intend to call. Examples:
gcloud services enable searchconsole.googleapis.com
gcloud services enable drive.googleapis.com
gcloud services enable sheets.googleapis.com
gcloud services enable bigquery.googleapis.com

Step 4: ADC with custom scopes (for calling Google APIs via curl or SDK)

This is the step most people get wrong. Use application-default login, not plain login, and include cloud-platform plus the target-API scope.

Build the scope string with explicit components to avoid quoting errors:

SCOPES="openid"
SCOPES="$SCOPES,https://www.googleapis.com/auth/userinfo.email"
SCOPES="$SCOPES,https://www.googleapis.com/auth/cloud-platform"   # REQUIRED
SCOPES="$SCOPES,https://www.googleapis.com/auth/webmasters.readonly"   # or your target scope
gcloud auth application-default login --scopes="$SCOPES"

When the browser opens: check every scope box on the consent page. If cloud-platform is unchecked, the login will succeed but any subsequent API call fails.

Common target scopes (add to SCOPES as needed)

API	Scope
Search Console (read)	https://www.googleapis.com/auth/webmasters.readonly
Search Console (read/write)	https://www.googleapis.com/auth/webmasters
Drive (read)	https://www.googleapis.com/auth/drive.readonly
Sheets	https://www.googleapis.com/auth/spreadsheets
Gmail (read)	https://www.googleapis.com/auth/gmail.readonly
Calendar	https://www.googleapis.com/auth/calendar
Analytics (read)	https://www.googleapis.com/auth/analytics.readonly
YouTube (read)	https://www.googleapis.com/auth/youtube.readonly

Step 5: Call the API

Always include x-goog-user-project header when using user/ADC credentials — it tells Google which project gets the API quota.

TOKEN=$(gcloud auth application-default print-access-token)
PROJECT=$(gcloud config get-value project)

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-goog-user-project: $PROJECT" \
  "https://<API>.googleapis.com/<path>" | jq

Troubleshooting

Error	Cause	Fix
unrecognized arguments: --scopes=... on gcloud auth login	Wrong command	Use gcloud auth application-default login --scopes=...
cloud-platform scope is required but not requested	Missing from --scopes	Add it to the scope list
cloud-platform scope is required but not consented	User unchecked it on consent screen	Rerun the ADC login and check all boxes
API requires a quota project	Missing header	Add -H "x-goog-user-project: $PROJECT"
SERVICE_DISABLED	API not enabled on project	gcloud services enable <API>.googleapis.com
caller does not have permission (on API resource)	The logged-in Google account lacks access to the resource itself	Grant access in the resource's own admin UI (e.g. Search Console → Users & permissions)

Service accounts (unattended use)

For cron jobs and non-interactive environments, prefer a service account:

gcloud iam service-accounts create my-sa --display-name="My SA"
gcloud iam service-accounts keys create sa-key.json \
  --iam-account=my-sa@YOUR_PROJECT.iam.gserviceaccount.com
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/sa-key.json"

Then grant the service account access to the target resource in that product's own UI (Search Console, Drive folder, Sheet, etc.) — IAM alone is not enough for most user-data APIs.

Done criteria

The setup is complete when:

1. gcloud --version prints a version.
2. gcloud config get-value project returns a project ID (not (unset)).
3. gcloud auth application-default print-access-token prints a token starting with ya29..
4. A sample API call with the quota-project header returns data (not PERMISSION_DENIED).