Choose CLI access
The CLI has 2 access modes. Pick one before your first command.
| Mode | Credentials | What the CLI reads |
|---|---|---|
| Local | Your own Google credentials: a service account or an OAuth client | Google directly. Data stays in a local Store on your disk |
| Hosted | Your gscdump.com account | Your hosted record. indexing inspect --yes spends URL Inspections. sitemaps inspect --engine google reads one Sitemap live |
auth login --mode local or auth login --mode hosted saves the mode for later commands.
--mode local or --mode hosted overrides it for one command. GSCDUMP_AUTH_MODE also overrides the saved mode.
If no mode is saved and GSCDUMP_API_KEY is set, the CLI uses Hosted mode. Otherwise it uses Local mode.
Run gscdump auth status --json to see the active mode. The commands reference lists profile options.
The CLI reads credentials from its configuration directory and from exported environment variables. It never reads a .env file, so a project's credentials stay with that project. To use a .env file, export its variables before you run gscdump.
Local mode
Local mode calls Google with your own credentials. gscdump.com is not involved.
Service account (recommended)
A service account key never expires, and it works on servers and in CI.
- In Google Cloud, create a project and enable the Google Search Console API.
- Create a service account, then create a JSON key for it.
- In Search Console, open the Site, then Settings > Users and permissions. Add the service account email as a user.
- Check the key and save its path:
gscdump auth login --mode local --service-account ./gsc-sa.json
gscdump auth status --json
gscdump sites --jsonFor scheduled runs, set GOOGLE_APPLICATION_CREDENTIALS or GSC_SERVICE_ACCOUNT_JSON to the key path instead.
OAuth client
Use an OAuth client when you want to sign in as yourself.
- In Google Cloud, enable the Google Search Console API.
- Create an OAuth client ID of type Desktop application.
- On the OAuth consent screen, set the publishing status to In production. In Testing status, Google expires refresh tokens after 7 days, and you must log in again each week.
- Set the client credentials, then log in:
export GSC_CLIENT_ID=your-client-id
export GSC_CLIENT_SECRET=your-client-secret
gscdump auth login --mode local
gscdump auth status --jsonFor an existing access token, set GSC_ACCESS_TOKEN. For renewable credentials, set GSC_CLIENT_ID, GSC_CLIENT_SECRET, and GSC_REFRESH_TOKEN together. gscdump auth status --json identifies the active source.
For a remote terminal, gscdump auth login --mode local --no-browser prints an authorization URL. The loopback flow may need port forwarding.
Google login does not connect Bing. Run gscdump bing login --mode local and gscdump bing sites --mode local --json separately. Use the exact Bing Site URL printed by bing sites for local Bing commands. See the Bing reference for OAuth and API key options.
Hosted mode
Hosted mode reads the record that gscdump.com keeps for your Sites. gscdump.com runs the sync. gscdump indexing inspect --yes requests new Google URL Inspections through the platform. gscdump sitemaps inspect --engine google reads one Sitemap live through the platform. It uses Google's API quota, without spending URL Inspections. Bing Sitemap inspection reads dated stored evidence.
Hosted login opens gscdump.com. Sign in, approve the CLI, then connect a Site. The CLI saves a session. You do not need to copy an API key. The session ends 90 days after you approve it. Then the CLI prints Your gscdump.com session expired. Run gscdump auth login --mode hosted to sign in again. SDK integrations and CI can use a user API key from Agent setup with --api-key or GSCDUMP_API_KEY.
gscdump auth login --mode hosted
gscdump sites --json
gscdump query --site example.com -d page -f jsonAfter login, the CLI prints one next step. If your hosted record has no Sites, the step is the connect link:
Next: connect a Site at https://gscdump.com/app/onboarding?step=connect-sites.
If Hosted access is not active, gscdump.com asks you to activate it first. gscdump auth status prints the same step while the record has no Sites.
If you select Cancel on the gscdump.com login page, the CLI prints Login cancelled in the browser. and exits 1.
Hosted mode runs these commands:
gscdump indexing inspect <url...> --yes requests new Google URL Inspections through the platform.
Pass up to 10 unique URLs. The platform enforces its shared quota. The CLI never retries these requests automatically.
siteslists your hosted Sites and their sync state.queryreads rows from the hosted record.sitemaps current,history,membership,lastmod, andexportread saved sitemap evidence.indexing urlslists saved URL Inspection results.indexing summaryshows the coverage ladder per day from saved URL Inspection results, with the time gscdump counted them.indexing watch list,add, andremovemanage Watched URLs. gscdump inspects each Watched URL every 7 days.bing login --site,sites,status,dump,inspect, andverifyuse the Bing connection saved on gscdump.com.
If gscdump sites --json prints [], your hosted record has no Sites. Commands that need a Site stop with the code NO_SITES.
If you logged in with the browser, connect a Site on gscdump.com. If an app gave you an API key, connect a Site in that app.
The NO_SITES message names that app when gscdump.com reports it, for example Connect a Site in Request Indexing.
Commands that need your own Google credentials require Local mode.
Examples: sync, inspect, query --live, sites add, sitemaps submit, indexing submit, and mcp.
In Hosted mode these commands stop and print the Local mode setup command.
For an MCP client in Hosted mode, connect it to https://gscdump.com/mcp.
For Bing, connect the Site in gscdump.com, then run gscdump bing sites --json and gscdump bing status --site s_SITE_ID --json. Use the hosted Site ID printed by bing sites for Bing commands.
Fix access errors
If a command prints Google credentials are missing, set up Local mode or Hosted mode as shown above.
If a command prints This command calls Google, so it needs Local mode, the command has no Hosted equivalent. Set up Local mode, or pass --mode local if Local credentials exist.
If sites is empty in Local mode, check the Google identity and the Site's Users and permissions.
If Hosted mode rejects the session, run gscdump auth login --mode hosted again.
If an OAuth refresh token expires after 7 days, set the OAuth consent screen to In production and run gscdump auth login --mode local --force.
gscdump doctor can check configuration. Do not paste credentials into an issue or agent prompt.
Continue with a result
Run the first query, or compare Google and Bing evidence after connecting both Search Engines. More setup: Start.