Google OAuth CLI Setup Gotchas

Manual Google OAuth setup for CLI tools has three common failure modes that are easy to avoid once identified. The Hacker News thread for the gws CLI documented users spending 30-45 minutes on these traps. The patterns apply to any CLI tool using Google OAuth, not just gws.

The Fastest Path: Automated Setup

Before going through the manual flow, check whether the tool offers automated setup. gws auth setup handles project creation, API enablement, OAuth consent screen configuration, and client credential creation automatically if you have gcloud already configured:

npm install -g @googleworkspace/cli
gws auth setup

This sidesteps every gotcha below. Only fall back to the manual flow when you hit organization restrictions that prevent automated project creation, or when you need explicit control over the configuration.

Trap 1: Wrong OAuth Application Type

When creating an OAuth client ID in the Google Cloud Console (APIs & Services > Credentials > Create Credentials > OAuth client ID), you must choose Desktop app as the application type.

The console defaults to Web application. Nothing warns you that you’ve chosen wrong. The authentication flow will appear to succeed — you’ll get a JSON file, you’ll set up credentials — and then it will fail at login time with an error that doesn’t indicate the application type as the cause.

If you created a Web application client, delete it and create a new one. There’s no way to change the application type after creation.

# After saving the correct Desktop app credentials to ~/.config/gws/client_secret.json
gws auth login

Trap 2: Missing Test User

After configuring the OAuth consent screen (APIs & Services > OAuth consent screen), you must add your own Google email address as a test user. This step is buried under a separate tab.

Without it, you’ll get a generic “Access blocked: [App name] has not completed the Google verification process” error when trying to log in. There’s no indication in the error that a missing test user is the cause — it looks like an app verification issue, not a configuration issue.

The fix: go back to the OAuth consent screen, click the “Test users” section, add your email address, and retry the login.

For personal or development use, you don’t need to complete the Google verification process. The unverified app warning you’ll see (“Google hasn’t verified this app”) is expected and safe. Click Advanced, then “Go to [app name] (unsafe)” to continue.

Trap 3: The Scope Limit

Unverified OAuth apps in testing mode are limited to roughly 25 OAuth scopes. This limit is enforced silently — you don’t get a clear error, you get a truncated scope authorization or a failure that’s hard to diagnose.

The gws CLI’s recommended “all services” preset includes 85+ scopes and will fail silently or throw an error if you try to authorize all of them at once.

The fix: authorize only the services you actually need. If you’re using Drive, Gmail, and Calendar, that’s a small fraction of the available scopes and will stay well under the limit:

# In MCP server mode, scope to specific services
gws mcp -s drive,gmail,calendar

# In auth setup, you can limit which service APIs get enabled

You can always add more services later with another gws auth login call. The scope limit is a testing-mode constraint; published apps (apps that have completed Google’s verification process) don’t have this restriction.

When gws auth login prompts interactively for credentials (if you haven’t saved the JSON file), it asks for your “OAuth ID.” What it actually wants is the client ID — the long string ending in .apps.googleusercontent.com. On the next prompt, it asks for the “client secret.”

Both values come from the JSON file you downloaded when creating the OAuth client. The prompt labels don’t match the names in the JSON, which causes confusion about which value goes where.

If you’ve saved the JSON file to ~/.config/gws/client_secret.json, the CLI reads it automatically and won’t prompt interactively. Alternatively, set environment variables:

export GWS_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GWS_CLIENT_SECRET="your-client-secret"

Multi-Account and Headless Setup

For multiple Google accounts, gws handles credential isolation natively:

# Log in with specific accounts
gws auth login --account work@corp.com
gws auth login --account personal@gmail.com

# List registered accounts
gws auth list

# Set a default, override per-command, or use environment variable
gws auth default work@corp.com
gws --account personal@gmail.com drive files list
export GOOGLE_WORKSPACE_CLI_ACCOUNT=personal@gmail.com

Each account gets its own encrypted credentials file at ~/.config/gws/credentials.<base64-email>.enc, with the encryption key stored in your OS keyring.

For headless environments (CI, servers, pipelines without browser access):

# On a machine WITH a browser: export credentials after interactive login
gws auth export --unmasked > credentials.json

# On the headless machine: point to the exported file
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list   # works without browser interaction

For server-to-server flows using a GCP service account with Domain-Wide Delegation:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com
gws drive files list

Auth Precedence

When multiple credential sources exist, the CLI resolves in this order (first match wins):

Access token (GOOGLE_WORKSPACE_CLI_TOKEN)
Credentials file (GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE)
Per-account encrypted credentials (from gws auth login --account)
Plaintext credentials (~/.config/gws/credentials.json)

You can also inject a pre-obtained access token, which is useful when gcloud already mints tokens:

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

“API Not Enabled” Errors

When you try to use a Workspace service for the first time, you may get a 403 error with reason accessNotConfigured. The fix: click the URL the CLI prints with the error, enable the API in the Cloud Console, wait about 10 seconds, and retry. Alternatively, re-run gws auth setup — it enables all required APIs automatically.

The manual OAuth flow doesn’t enable APIs automatically; it only creates the OAuth credentials. Each service (Gmail, Drive, Calendar, etc.) needs its corresponding API enabled separately in the Cloud Console before the CLI can use it.