Index of every page on this site: llms.txt
Skip to content

Run your first Search Console query

Start with one query. You need Node.js 22.13 or later in the 22 release line, or Node.js 24 or later. You also need access to a Google Search Console Site.

Choose an access mode

The CLI has 2 access modes. Choose access compares them.

  • Local mode calls Google with your own credentials. A service account is the simplest path, and its key never expires.
  • Hosted mode reads the record that gscdump.com keeps for your Sites. 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.

Install and connect

For Local mode with a service account, add the service account email as a user of the Site in Search Console first.

npm install -g @gscdump/cli
gscdump auth login --mode local --service-account ./gsc-sa.json
gscdump auth status --json
gscdump sites --json

For Hosted mode, log in and connect a Site on gscdump.com:

gscdump auth login --mode hosted
gscdump sites --json
gscdump query --site example.com --dimensions date --limit 7 --format json

Use a Site printed by sites. A domain Site may appear as sc-domain:example.com; pass --site example.com in the query. The CLI saves its credentials in its private configuration directory.

Run one live query in Local mode

First live query

Input

gscdump query --live --site example.com --dimensions date --limit 7 --format json

Check the result

Returned rows contain a date, clicks, and impressions. JSON metadata identifies the source as live.

If it fails: If rows are empty, check the Site and final date window. If access fails, check sites and auth status.

Site: example.com; window: latest final 28 days; source: live Google Search Console; result fields from the CLI contract.

gscdump query --live --site example.com --dimensions date --limit 7 --format json

Each returned row has a date and Search Analytics metrics such as clicks and impressions. Read meta.source to confirm live. --live needs Local mode. In Hosted mode, drop --live: meta.source is then hosted. The query reference lists dimensions and filters. Live queries default to 28 days ending three days ago in Search Console's Pacific reporting calendar. The newest days may still change.

CheckMeaning
Rows with clicks and impressionsGoogle returned data for this Site and window.
Empty rowsThe Site may have no matching data. Check its exact identity and date window.
Permission errorCheck the Google connection and Site access in gscdump sites --json.
Quota errorUse the retry time from the CLI. Do not loop immediately.

Run this with an agent

Install the gscdump agent skill, then adapt this prompt to your Site.

Use the installed gscdump skill. List my Search Console Sites and ask which one to query. Show page clicks, dates, and meta.source.

Pick your next task

Query and export rows, save history in a Store, or review traffic each week. The Start guides cover access and agents.