gcloud Skill

Patterns for Google Cloud CLI operations, OAuth authentication with custom scopes, and making authenticated calls to Google APIs including Search Console, Webmaster Tools, and other Workspace APIs.

Behavioral Classification

Type: Guided Decision

Directive: ASK, THEN EXECUTE

Identify which Google API and operation is needed, then execute the appropriate auth + API call pattern.

Critical: gcloud Auth Scope Limitations

gcloud auth login and gcloud auth application-default login grant a fixed set of Cloud-platform scopes. They do not include Google Workspace API scopes such as:

Workaround: gcloud auth application-default login --scopes=<scope>,https://www.googleapis.com/auth/cloud-platform appears to work but gcloud's cloud-platform requirement overrides custom scopes at token generation time. Use the Python localhost OAuth flow instead.

Pattern 1: Custom-Scope OAuth Token (Workspace APIs)

When a Workspace API scope is needed, run the bundled helper script:

# Generates a scoped token and saves it to /tmp/google_token.json
python3 ~/.claude/skills/gcloud/scripts/oauth_token.py \
  --scope "https://www.googleapis.com/auth/webmasters"

The script:

1. Starts a local HTTP server on port 9876
2. Opens a browser OAuth consent screen
3. Captures the auth code automatically via redirect
4. Exchanges it for an access token
5. Saves token JSON to /tmp/google_token.json

Then read the token in subsequent API calls:

import json
with open('/tmp/google_token.json') as f:
    TOKEN = json.load(f)['access_token']

Pattern 2: Enable a GCP API

Before calling any Google API, ensure it is enabled for the active project:

# Check active project
gcloud config get-value project

# Enable an API
gcloud services enable searchconsole.googleapis.com
gcloud services enable drive.googleapis.com
gcloud services enable sheets.googleapis.com

# List all enabled APIs
gcloud services list --enabled

Pattern 3: Authenticated REST Calls

All Google API calls require Authorization: Bearer <token> and — for APIs accessed via application credentials — X-Goog-User-Project: <project-id>.

import json, urllib.request

with open('/tmp/google_token.json') as f:
    TOKEN = json.load(f)['access_token']

PROJECT = subprocess.check_output(['gcloud', 'config', 'get-value', 'project']).decode().strip()

def gapi(url, method='GET', data=None):
    req = urllib.request.Request(url, data=data, method=method)
    req.add_header('Authorization', f'Bearer {TOKEN}')
    req.add_header('X-Goog-User-Project', PROJECT)
    if data is not None:
        req.add_header('Content-Length', str(len(data)))
    try:
        with urllib.request.urlopen(req) as resp:
            return resp.status, json.load(resp)
    except urllib.error.HTTPError as e:
        return e.code, json.loads(e.read())

Pattern 4: Search Console API

Requires scope: https://www.googleapis.com/auth/webmasters

import urllib.parse

SITE_URL = urllib.parse.quote('https://www.example.com/', safe='')

# Submit a sitemap
status, body = gapi(
    f'https://www.googleapis.com/webmasters/v3/sites/{SITE_URL}/sitemaps/'
    + urllib.parse.quote('https://www.example.com/sitemap-index.xml', safe=''),
    method='PUT', data=b''
)
# 204 = success

# Get sitemap status
status, body = gapi(
    f'https://www.googleapis.com/webmasters/v3/sites/{SITE_URL}/sitemaps/'
    + urllib.parse.quote('https://www.example.com/sitemap-index.xml', safe='')
)
# body contains: path, isPending, lastSubmitted, warnings, errors

# List all sitemaps
status, body = gapi(
    f'https://www.googleapis.com/webmasters/v3/sites/{SITE_URL}/sitemaps'
)

# List verified sites
status, body = gapi('https://www.googleapis.com/webmasters/v3/sites')

Note: "Request Indexing" (URL Inspection → Request Indexing in GSC dashboard) has no API equivalent. It must be done manually in the GSC web interface. The Google Indexing API only supports JobPosting and BroadcastEvent schema types, not general pages.

Pattern 5: Token Scope Verification

Always verify a token has the required scope before making API calls:

import urllib.request, json

def check_scopes(token):
    req = urllib.request.Request(
        f'https://www.googleapis.com/oauth2/v1/tokeninfo?access_token={token}'
    )
    with urllib.request.urlopen(req) as resp:
        info = json.load(resp)
    return info.get('scope', '').split()

scopes = check_scopes(TOKEN)
print('Granted scopes:', scopes)

Common Errors

Quick Reference: Auth Decision Tree

Need to call a Google API?
│
├─ Cloud platform API (GCP, BigQuery, GCS, etc.)
│   └─ Use: gcloud auth print-access-token
│
└─ Google Workspace API (Search Console, Drive, Gmail, Sheets, etc.)
    └─ Use: python3 ~/.claude/skills/gcloud/scripts/oauth_token.py --scope "<scope>"

Environment Variables

References

• Scope Patterns — full list of Google API scopes and their use cases
• oauth_token.py — standalone OAuth helper script