Skip to content
Skills Library
DevOps & cloud · Automation

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.

Licence
MIT
Last repository change
06.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
14
Deprecation

No signals detected. Repository changed on 06.10.2026, without references to retired models or APIs.

Licence

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

  1. When to use this skill
  2. Key facts (memorize — these were the gotchas)
  3. Step 1: Install
  4. Step 2: User login (for running gcloud commands)
  5. Step 3: Pick a project and enable the API you need
  6. Step 4: ADC with custom scopes (for calling Google APIs via curl or SDK)
  7. Step 5: Call the API
  8. Troubleshooting
  9. Service accounts (unattended use)
  10. Done criteria
Original SKILL.md headings · 142 lines, 865 words
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,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.