Use existing gcloud auth

If you already run gcloud on this machine, the desktop app can use its Application Default Credentials instead of a separate Google sign-in. Nothing is copied, no token is stored by Querylab.io, and revoking in gcloud revokes in the app. Use it when you want one Google login for the terminal and the IDE, or when a browser sign-in isn't an option.

# Install the Google Cloud CLI if you don't have it
brew install --cask google-cloud-sdk        # macOS
# Windows and Linux: https://cloud.google.com/sdk/docs/install

# Create Application Default Credentials (opens a browser)
gcloud auth application-default login

Then, in the app, click Continue with local gcloud on the first screen. The step-by-step with the cards is on Connecting to BigQuery; this page is about what happens underneath.

What the app runs

• gcloud installed — on PATH, or in one of the standard install locations

• gcloud auth application-default login completed at least once
• The ADC account can see at least one project with BigQuery enabled

The app never reads application_default_credentials.json itself. Whenever it needs a token — at launch, and again once the current one expires — it runs:

gcloud auth application-default print-access-token

and keeps the result in memory. It then calls Google’s userinfo endpoint with that token to learn the account’s email, which becomes your identity in the app. No token, and no email, is sent to Querylab.io for this; the BigQuery API is called directly from the app.

Because gcloud is the source of truth, gcloud auth application-default revoke or a re-login with another account takes effect at the next token refresh (the next launch, or the first request after the current token expires), or immediately if you sign out and back in.

Where it looks for gcloud

PATH first (which gcloud, or where gcloud.cmd on Windows). Apps launched from Finder or the Start menu get a minimal PATH, so the app also checks the usual install directories:

A gcloud installed somewhere else (a custom prefix, a version manager) is only found if it’s on PATH when the app starts. Launching the app from a terminal (open -a Querylab on macOS) inherits your shell’s PATH.

Which scopes the token has

The token has whatever scopes you granted when you ran the login. The app doesn’t pass --scopes to print-access-token and can’t ask for more later; gcloud restricts what ADC tokens may carry. The default login grants cloud-platform, which covers BigQuery, project listing, and scheduled queries. Which features need which scopes, and the login command for Google Sheets export, are on Authentication.

Which project gets billed

BigQuery jobs are billed to the project you run them in (the Run on project in the tab’s status-bar popover), not to gcloud’s quota project. You can ignore gcloud auth application-default set-quota-project and the “quota project” warning gcloud prints at login; the app doesn’t send a quota-project header.

What the app does with your gcloud project

The app reads gcloud’s active project once, in the same order gcloud does: the CLOUDSDK_CORE_PROJECT environment variable, then the [core] project of the active configuration under ~/.config/gcloud/ (%APPDATA%\gcloud\ on Windows; CLOUDSDK_CONFIG is honoured). It uses it for one thing: pre-filling the Missing a project? field in Settings → BigQuery when you have no projects configured yet and that project isn’t in the list Google returned.

It is not “the” project. Which projects appear in the tree, and which one a tab runs on, are set in Querylab.io, exactly as with Google sign-in; gcloud config set project afterwards changes nothing in the app.

When ADC and Google sign-in disagree

ADC and Google sign-in can coexist: if a Google sign-in already exists in the app and ADC is used on top of it, the app checks that both are the same Google account. If not:

Run that command and try again. There is no check when ADC is your only sign-in: the ADC account is your account.

Troubleshooting

The card on the first screen shows one of these lines. Each maps to a gcloud state:

After fixing, click the re-check arrow on the card. No restart is needed. The card shows the short version of gcloud’s error; for the full text, run the same command in a terminal:

# Check what the app will see
gcloud auth application-default print-access-token | cut -c1-12
gcloud config get-value project
gcloud config get-value account

# Start over with a specific account
gcloud auth application-default revoke
gcloud auth application-default login --account=you@example.com