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 --yesrequests new Google URL Inspections through the platform.gscdump sitemaps inspect --engine googlereads 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 --jsonFor 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 jsonUse 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
Input
gscdump query --live --site example.com --dimensions date --limit 7 --format jsonCheck the result
Returned rows contain a date, clicks, and impressions. JSON metadata identifies the source as live.
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 jsonEach 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.
| Check | Meaning |
|---|---|
| Rows with clicks and impressions | Google returned data for this Site and window. |
| Empty rows | The Site may have no matching data. Check its exact identity and date window. |
| Permission error | Check the Google connection and Site access in gscdump sites --json. |
| Quota error | Use 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.