gcloud-setup
/gcloud-setup
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
- extractumio ↗
- Repository
- extractum-skills ↗
- Licence
- MIT
- Last repository change
- 06.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 14
No signals detected. Repository changed on 06.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author 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.
How it works
- When to use this skill
- Key facts (memorize — these were the gotchas)
- Step 1: Install
- Step 2: User login (for running gcloud commands)
- Step 3: Pick a project and enable the API you need
- Step 4: ADC with custom scopes (for calling Google APIs via curl or SDK)
- Step 5: Call the API
- Troubleshooting
- Service accounts (unattended use)
- Done criteria
SKILL.md preview
--- 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: info@extractum.io 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 ```bash # 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: ```bash 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) ```bash 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 ```bash # 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: ```bash 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. ```bash 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: ```bash 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`).
Versions
The database has no other skills named gcloud-setup.
Database snapshot: 13.11.2026 · package version 91d0cab0b1e6 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 2 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100gcloud
Expert Google Cloud CLI guidance. Use when the task involves gcloud commands or the Google Cloud SDK — installing or updating the CLI and components (bq, gsutil, kubectl, gke-gcloud-auth-plugin, alpha/beta), gcloud init, authentication issues (gcloud auth login vs… - 85gcloud-auth-verification
Guidelines for identifying and resolving missing Google Cloud authentication and Application Default Credentials (ADC). Use this skill if `gcloud`, `bq`, `dataform`, or Python libraries return authentication errors. - 100gcloud
为跨 Google Cloud Platform (GCP) 服务和基础设施的 gcloud CLI 操作提供安全关键的校验、防护措施和数据精简。 在规划、生成、构造、提议、描述或执行任何 gcloud CLI 命令时使用——包括回答关于 gcloud 语法或标志格式的问题时。 不要在编写 Google Cloud 客户端库代码或原始 REST/gRPC API 请求时使用。 - 100gcloud
Use the gcloud CLI from a Centaur sandbox, where iron-proxy injects Google Cloud credentials on the wire. Use before any gcloud command, Google Cloud deploy, Cloud Run, Cloud Build, Artifact Registry, Cloud Storage, or IAM task, and whenever gcloud reports no credentialed… - 90gcp-setup
🐉 Initial Google Cloud environment verification and authentication setup. Use when starting a new session to ensure correct identities across gcloud, ADC, and kubectl. - 100gcloud
Google Cloud CLI (gcloud/gsutil/bq) for GCP operations from agentbox: Compute Engine VMs, Identity-Aware Proxy (IAP), Secret Manager, Cloud Run, Artifact Registry, Cloud NAT/firewall. Use when a task involves deploying to or operating Google Cloud — standing up a VM behind IAP,…