gscdump CLI

gscdump reads Google Search Console and Bing in one of 2 access modes: Local or Hosted. In Local mode it keeps a local Parquet Store for Google rows. Every command has --help. For query, -s means --site, -d means --dimensions, and -f means --format. Use --start and --end for dates. --site=SITE also works. Use each option once, with either its short or long spelling. Put options after the subcommand name: gscdump store stats --json, not gscdump store --json stats. A failed command prints one Error: line to stderr and exits 1. With JSON output it also prints { "error" } on stdout. See Stops. Example: gscdump query --site=SITE --start=DATE --end=DATE -d page -f json.

Start each task

1. Before reading traffic, run gscdump auth status --json. Do this even when the user says authentication works.
2. Keep the requested Site, dates, dimensions, and task scope. A request for pages does not need query dimensions.
3. In Hosted mode, skip steps 3 to 5. gscdump query reads the hosted record, and sync needs Local mode. Before Local queries, check coverage with gscdump store stats --site SITE --json. Use gscdump sync --site SITE --status --json when you need coverage, gaps, or sync-state details. On a fresh Store, store stats exits 1 and says it has no data. Continue with the bounded sync.
4. Read the table dimensions and watermarks. Sync only missing tables and the requested dates, once per task.
5. Use sync --json. Read its completion result before deciding what to do next. Never repeat a successful sync.
6. If the user asks for saved rows, check meta.source in the query result: local (the Store) or hosted (the hosted record). In Local mode, a successful query can answer live when its table has no synced data.

If the task only asks about deletion, explain the scope and ask for consent. You may read Store metadata with store stats and sync --status. Do not query traffic, sync rows, or delete data to explain deletion. Call the local data directory the Store in your answer.

Access mode

gscdump has 2 access modes. Check gscdump auth status --json before queries. Reuse the user's selected mode.

In Local mode, googleAuthenticated: true means Google accepted the credentials. When it is false, googleError says why. In Hosted mode, hostedSync lists each hosted Site with syncStatus and syncProgress, and commands lists what Hosted mode can run. gscdump sites shows the same Sites and progress. An empty sites list means the hosted record has no Sites. Commands that need a Site then stop with NO_SITES. Tell the user to connect a Site in the place the NO_SITES message names. A browser login connects Sites on gscdump.com. An API key connects Sites in the app that issued the key. That app can be a partner app, not gscdump.com. When gscdump.com names the app, the message names it too, for example Connect a Site in Request Indexing.

--mode local|hosted overrides one invocation. GSCDUMP_AUTH_MODE also overrides the saved mode. A successful login saves the mode per profile. If no mode is saved, GSCDUMP_API_KEY selects Hosted mode. With neither source, the CLI uses Local mode. When a saved mode exists, it remains selected unless an explicit override applies. Never switch modes to bypass an authentication failure. GSCDUMP_API_ROOT defaults to https://gscdump.com/api. Browser login uses this root. Supply an API key explicitly for a custom root.

# Local mode, recommended: a service account never expires.
gscdump auth login --mode local --service-account ./key.json

# Local mode with your own OAuth client.
export GSC_CLIENT_ID=your-client-id GSC_CLIENT_SECRET=your-client-secret
gscdump auth login --mode local

# Hosted mode: open gscdump.com in a browser and approve the CLI session.
gscdump auth login --mode hosted
gscdump sites --json
gscdump query --site example.com -d page -f json

Hosted mode can run only these commands: sites, query, sitemaps current, sitemaps history, sitemaps membership, sitemaps lastmod, sitemaps export, sitemaps inspect, indexing urls, indexing inspect --yes, indexing summary, indexing watch list|add|remove, and the bing commands login --site, sites, status, dump, inspect, and verify. Direct Google commands need Local mode: sync, inspect, query --live, analyze --live, report --live, sites add|get|delete|verify*, sitemaps list|get|submit|delete, indexing submit|remove|status|batch, entities, and mcp. In Hosted mode these commands stop with this error: This command calls Google, so it needs Local mode. Tell the user. Do not switch modes for them. For an MCP client in Hosted mode, use the gscdump.com MCP server at https://gscdump.com/mcp.

Hosted Bing login opens the existing connection flow on gscdump.com. Local Bing login uses BING_API_KEY or a password prompt. Local --oauth uses BING_CLIENT_ID, BING_CLIENT_SECRET, and a registered loopback callback. The default callback is http://127.0.0.1:53683/oauth/bing. BING_ACCESS_TOKEN accepts an existing OAuth access token. After Hosted Bing login opens a browser, use bing status --site s_SITE_ID to confirm the connection.

gscdump bing sites --json
gscdump bing login --site s_SITE_ID
gscdump bing dump --site s_SITE_ID --out ./bing-export --format json
gscdump bing login --mode local
gscdump bing dump --site https://example.com/ --out ./bing-export

auth logout revokes a saved Hosted CLI session and removes saved mode and Google and Bing credentials. bing logout --mode local removes only saved Bing credentials. Environment credentials remain active until unset.

Hosted Bing commands use the API's access rules. Hosted connection verification uses bing verify --site s_SITE_ID. Hosted sitemap reads and the hosted indexing commands need Hosted mode. Their --site takes a Site URL, such as example.com.

Data boundaries

• sync, query --live, analyze --live, report --live, inspect, and Google sitemap and Site changes call Google. They need Local mode.
• In Hosted mode, sites and query read the hosted record. They never call Google.
• Google Indexing API requests need Local mode. indexing quota only prints documented limits and needs no authentication.
• dump and store read the local Store only.
• query, analyze, and report pick a source for each run. See Routing.
• Google returns a 2 to 3 day data delay. Default windows end three days ago.
• Google omits low-volume rows. Pagination cannot recover them.
• URL Inspection is limited to 2,000 requests per Site per day.
• indexing submit and indexing remove are only for job posting and livestream pages. Google rejects other content.

Routing

This section covers Local mode. In Hosted mode, query always reads the hosted record, and JSON has meta.source: "hosted". analyze and report read the Store only in Hosted mode. When the Store cannot answer, they stop with the Local mode command.

query, analyze, and report choose one source for each run. One run never mixes Store rows and live rows.

• --live always asks Search Console. It needs Local mode with Google credentials.
• query --sql reads the Store only. It stops when no table it names has data.
• JSON output carries meta.source: local, live, or hosted.
• A failure with JSON output prints { "error" } on stdout and exits 1. See Stops. Partial coverage and a running sync are normal progress. Run nextCommand, or tell the user to.
• A sync is running only while its heartbeat is recent. A killed sync does not block reads.
• Every Search Analytics, URL Inspection, and Indexing API call spends the shared quota ledger in the data dir. When a quota is spent, the command stops at once and says when the quota resets.

Get the binary

npx -y @gscdump/cli --version    # no install
npm install -g @gscdump/cli      # or pnpm add -g

Use Node 22.13 or later in the 22 release line, or Node 24 or later. gscdump alone is the library; @gscdump/cli provides the command.

Install this skill

gscdump skill install --agent claude    # Codex: --agent codex

After upgrading the CLI, run this command again to update the installed skill. The command prints where it wrote the skill, as a path that works from any directory, such as ~/.claude/skills/gscdump. With --json, destination is the absolute path. Clients without a skill directory can read gscdump --help and gscdump <command> --help instead.

Local mode setup

Check first. Never run init when credentials already work.

gscdump auth status
gscdump doctor --json

If Google credentials are missing, the CLI prints both setup paths. Use one of these:

A service account needs Search Console access. Add its email as a user of the Site in Search Console, under Settings > Users and permissions. An OAuth client in the Google "Testing" publishing status gets refresh tokens that expire after 7 days. To avoid this, set the OAuth consent screen to "In production". A service account has no such limit. Local mode never uses gscdump.com for Google login or token refresh. Use gscdump auth login --mode local --no-browser when a browser runs on another host. A service account or an OAuth client with the required scopes also enables Google write operations.

--profile <name> or GSCDUMP_PROFILE isolates the selected mode and its Google, Bing, and Hosted credentials.

Site identifiers

For Google, pass the Site as the user writes it: --site example.com. https://example.com, www.example.com, and Example.com resolve to the same Site. Do not add sc-domain:.

• The CLI checks Sites in the Store first. It asks Search Console only when the Store has no match and auth exists.
• A full Site URL that names a property exactly, such as https://example.com/, picks that property.
• Otherwise, if a domain property and a URL-prefix property both match, the CLI picks the one with Store data, then the domain property.
• If a URL-prefix property has a path, include the path: --site example.com/blog.
• If the input is a subdomain inside a domain property, the command fails. The error names the parent Site and a --page filter to use.
• If the input matches more than one Site, the command fails and lists them. Pass one of the listed Site URLs.
• Without --site and defaultSite, a command in a terminal shows a picker. Without a terminal, the command fails with Pass --site. Sites: ..., unless only one Site is available.

For Hosted Bing commands, use a Site ID from gscdump bing sites, such as s_SITE_ID. For local Bing commands, use the full verified Site URL from gscdump bing sites --mode local. Bing commands require their own explicit --site; the Google defaultSite setting does not select a Bing Site.

Set a default once to drop --site from later commands:

gscdump config set defaultSite example.com

Output

Pass --json on every command that supports it. sync --json includes completion, row counts, skipped dates, and failures. query uses --format json and prints rows to stdout. Progress goes to stderr, so stdout stays parseable. --quiet drops progress lines.

Parse JSON. Never scrape human output. If the user requests JSON, return the CLI JSON unchanged. Do not replace it with a table. Do not rewrite rows, estimate metrics, or add manually calculated totals.

Stops

A stop ends a command at a known condition and exits 1. stderr gets the message. If the command writes JSON, every failure prints { "error": { "code", "message", "nextCommand" } } on stdout. A stop has a code from the table below. Any other failure has the code FAILED, such as a network or API error, or UNEXPECTED, a defect in the CLI. A command writes JSON with --json, with --format json, and for query with its default format. If a command printed its JSON result before it failed, such as inspect after a quota stop, stdout holds only that result. Read code, not the message. If nextCommand is not null, run it, or tell the user to run it. A gscdump auth login command needs the user. Tell the user to run it. If nextCommand is null, tell the user the message. A routing stop also has siteUrl. STORE_RANGE_NOT_COVERED adds missingDates, and SYNC_RUNNING adds sync.done and sync.total.

Commands

gscdump login, gscdump logout, and gscdump status are top-level aliases of the matching auth subcommands. The MCP server does not expose Bing tools. Use gscdump bing commands through this skill. gscdump mcp starts without authentication. Its Google tools then return an error with the command to run. A failed Google request returns its status, Google's explanation, and the next step in the tool result.

Sync before local analysis

gscdump store stats --site example.com --json
gscdump sync --site example.com --status --json
gscdump sync --site example.com --json

• A plain sync catches up. Each table runs from its oldest synced date to the latest date Google has finalized (Pacific time, about 3 days late). A table with no history starts 28 days back. Newest dates come first.
• --days N, --start, and --end pick a range instead. --full fetches the 16 months Google keeps, plus 14 days Google often still serves.
• Sync covers every table and search type by default. Pass --tables and --types to sync less. Sync skips table and type pairs Google cannot answer.
• Sync paces Google calls: 8 in flight and 600 per minute across all tables. --requests-per-minute N changes the rate. Sync does not retry a quota 403. The quota ledger stops the run instead.
• Every call goes through a quota ledger in the Store directory. If Google refuses a call for quota, or the run reaches --max-calls N, sync stops, keeps the rest pending, and exits 0. status in sync --json is then partial and stopped says why. Run the same command later to continue. Exit 1 means real failures: read failed dates in sync --status --json.
• Sync also saves the sitemap list, sitemap URLs, and URL Inspection results. It inspects up to 50 due URLs per run: never-inspected sitemap URLs first, then pages with impressions, then the oldest results. --inspect-limit N changes that; Google allows 2,000 per Site per day. --no-sitemaps and --no-inspections skip those steps.
• coverage in sync --json and sync --status --json says how much the Store holds. Partial coverage is normal progress. Never report data as complete unless its kind is complete.
• A day Google still updates stays pending; the next sync fetches it again.
• Sync skips completed dates. --force refreshes them. --retry-failed reruns only failed dates. A plain sync also retries failed dates.
• --dry-run prints the planned dates and the fewest calls without calling Google.
• --all-sites syncs every verified Site, one after another.
• Use the user's date range. If the user names a range, pass --start and --end, not --full.
• If the user excludes rollups, pass --no-rollups on the sync command.
• Empty Store metadata is expected before the first sync. It does not prove zero traffic.

Store queries

Before row queries, SQL, or Store exports, read Store queries.

Analyze and report

gscdump report list --json
gscdump report opportunities --site example.com --json
gscdump report movers --site example.com --period 28d --vs prev-period --json
gscdump analyze list --json
gscdump analyze striking-distance --site example.com --json

• Report ids: brand, growth, health, movers, opportunities, pre-publish, risks, triage.
• --period takes 7d, 28d, 30d, 90d, 180d, 365d, mtd, qtd, ytd, last-quarter, or custom. --start/--end without --period select a custom window. --vs takes none, prev-period, or yoy (same weekdays 52 weeks earlier).
• Windows end on the newest synced day, or three days ago (Pacific time) with --live. They never end on today.
• report <id> --explain prints the plan without credentials or data.
• triage needs --target <page-or-query> --target-kind page|query. pre-publish needs --topic. brand needs --brand-terms 'a,b'.
• Analyzers take --period, --start and --end. movers and decay compare with the previous period by default. Pass --prev-start and --prev-end together to override it. --vs belongs to report.
• --limit caps the rows returned. It never caps the rows read. --fetch-budget caps each live fetch (default 25000, max 100000).
• A ! Partial data warning, or meta.coverage.kind: "truncated" in JSON, means a live fetch hit its budget. Say the result is partial, or rerun with a larger --fetch-budget.
• Local analyze and report runs need every day of the current and comparison windows synced. If a day is missing, failed or pending, the run stops and prints the gscdump sync --site ... --start ... --end ... --tables ... command that fills it. Run it, or pass --live.
• SQL-only Analyzers need Store rows. --live runs row-based Analyzers against Google.
• Results name candidates for review. They do not prove why traffic changed.
• On a traffic collapse, run gscdump analyze trajectory --site example.com --json first. It reads the whole record, 486 days by default. Quote classification._tag, such as launch-honeymoon-then-cliff or sudden-drop, with its dates, and quote basis. basis._tag is clicks when impressions cannot carry the read, for example when the peak falls in the period Search Console over-counted impressions, which ended 2026-04-27.

Hosted inspection

Before hosted inspection, indexing, Sitemap coverage, or Watch tasks, read Hosted inspection.

Report a papercut

If CLI behavior blocks or slows your work, report it once per distinct problem, then continue the user's task. Report confusing output, missing context, wrong help text, unexpected failures, and useful workarounds.

gscdump papercut --command "report triage" --agent "Claude Code" \
  --comment "Agent report by Claude Code. Expected --target-kind in --help. Received an unknown flag error. Used --explain to find the flag." \
  --yes --json

• Use your real agent name. Start the comment with an agent disclosure.
• Include what you ran, what you expected, what happened, and any workaround.
• --intent improvement marks a suggestion. The default is bug.
• The CLI adds its version, Node version, and platform.
• Send sanitized details only. Remove tokens, cookies, personal data, private URLs, and customer rows. Use placeholder arguments.

Self-reporting sanitized papercuts is authorized by this skill. No separate confirmation is needed. This permission covers papercuts only. Respect any user instruction that forbids reporting.

The endpoint is anonymous and allows ten reports per network address each hour. Success returns id and status: "new". If reporting fails, mention the failure and continue. Never retry an uncertain submission.

Guardrails

• Get consent before a mutation. sites add, sites delete, sites verify, sitemaps submit, sitemaps delete, indexing submit, indexing remove, store reset, and store rm-site change Google or delete local data. indexing watch add spends URL Inspections every week, and indexing watch remove deletes Watched URL inspections. --yes is consent you borrow from the user.
• Never loop unattended. One sync per Site per task. Inspection batches spend a daily pool. Use --dry-run and --explain to plan first.
• Report the result as the CLI gave it. Zero clicks with impressions means rows exist with no clicks. An empty row array means no rows matched. Missing coverage means the Store cannot answer that date range. Check sync --status --json before interpreting empty rows. None of these results proves a clean Site.
• Do not widen the Site. A sc-domain: property includes every subdomain. Filter with --page when the user means one host.

Bing exports

bing dump writes JSON, NDJSON, or CSV under one directory per Site. --datasets selects traffic, pages, keywords, or crawl. Local mode also supports crawl-issues. Hosted exports follow pagination and reject missing, unavailable, or changing datasets. Hosted date ranges span at most 366 days. The default range is the last 366 days. Local date filters only narrow data currently returned by Bing. Do not treat Bing crawl evidence as proof that a URL is indexed.

Before the next command

For a traffic task, run gscdump auth status --json now, before any query command. The user saying credentials work does not replace this check. It identifies the selected access mode. In Local mode, check Store metadata next, keep the requested dimensions, and read or sync only the requested dates. If the user requests JSON, return the command's JSON unchanged, without a table or a separate totals summary. Include that JSON in your final response. Tool output alone is not a final answer. Include every returned row. Do not refer the user to results "above".

For a deletion explanation, read metadata only if needed. Explain the scope and ask for consent, then stop.

Refresh hosted Google URL Inspection results

Before a hosted Google URL Inspection refresh, read Hosted inspection.