Commands
| Command | Description |
|---|---|
init | Set up authentication and the local Store. --mode local|hosted saves the access mode. Without a terminal it never prompts |
auth | Manage authentication (status, login, logout, refresh) |
bing | Connect Bing, list sites, dump datasets, inspect URLs, and check hosted verification |
config | Manage CLI configuration (show, set, unset, path, validate) |
doctor | Health checks: auth, scopes, dataDir writability, API reachability |
sites [--owner-only] [--with-sitemaps] | List available GSC sites |
sites add <url> / sites delete <url> [--yes] | Register or remove a Site in Search Console (add registers in unverified state) |
sites verify-token <url> [--method] / sites verify <url> [--method] | Get a verification token, then trigger ownership verification (META/FILE/DNS_TXT/DNS_CNAME/ANALYTICS/TAG_MANAGER) |
sitemaps | List, submit, or delete Google sitemaps; probe live URLs; read hosted snapshots (current, history, membership, lastmod, export) with --site |
inspect <url...> [--file] | URL inspection for one or more URLs; renders Indexing Evidence, rich results, and AMP, and saves each result to the Store |
indexing | Notify Google about URL changes (submit, remove, status, batch, batch-status, quota); supports --retries. indexing urls --status not_indexed lists hosted URL Inspection results. indexing inspect <url...> --yes refreshes up to 10 hosted URLs using the shared URL Inspection quota. indexing summary shows the hosted coverage ladder per day with its capture time. indexing watch list|add|remove manages hosted Watched URLs |
sync | Sync GSC data, sitemaps, and URL Inspection results to the local Store; --inspect-limit, --max-calls, --all-sites, --no-sitemaps, --no-inspections, --retry-failed, --dry-run |
query | Run a search analytics query (the Store when it covers the dates, see Routing; --live hits GSC API). Filters: --query, --page, --country, --device, --search-appearance, --type, --data-state, --aggregation-type. --explain previews the request body; --output - writes to stdout. --sql runs DuckDB SQL over the Store views; --schema lists them. |
dump | Export the Store, inspections, sitemaps, and Bing data (--format parquet|csv|json|ndjson|sqlite|duckdb, --tables, --all-sites, --no-bing). Analytics rows have site and search_type |
analyze <tool> | Run an SEO Analyzer against the Store. Live-capable Analyzers can read Google when the Store is empty or with --live |
entities | Read saved URL inspections with show; save Google Indexing API notification times with indexing snapshot |
store stats | Show row/byte counts per table and on-disk footprint |
store compact | Compact older data into weekly, monthly, and quarterly tiers (--dry-run) |
store gc | Delete retired/unreferenced files and expire hourly files created over 90 days ago; --dry-run previews retired entries only |
store rm-site / store reset | Delete one Site's data or reset the Store; inspect --help before use |
store rollups rebuild | Rebuild post-sync rollup tables |
report <id> / report list | Run or list Reports; --explain previews a plan |
profile | Create, select, list, or delete credential profiles |
mcp | Start the MCP server for AI assistants |
skill install [--agent claude|codex] [--target <dir>] | Copy the packaged gscdump agent skill (SKILL.md) into an agent skill directory |
papercut --command <cmd> --comment <text> --agent <name> [--intent bug|improvement] --yes | Report a CLI problem to gscdump.com; anonymous, ten per hour per network address |
store gc --dry-run excludes expired hourly files and unreferenced files from its preview.
The deletion run also removes those files. Hourly expiry uses file creation time, not the dates within the data.
Global flags
--no-color/NO_COLORenv: strip ANSI from stdout (stderr keeps colour for interactive use).--config-dir <path>/GSCDUMP_CONFIG_DIR: override~/.config/gscdump.--profile <name>/GSCDUMP_PROFILE: separate tokens and config to a profile under~/.config/gscdump/profiles/<name>(separate Google credentials).--mode local|hosted/GSCDUMP_AUTH_MODE: override the saved access mode. Hosted reads use saved data.indexing inspect --yesrequests new Google URL Inspections through the platform.sitemaps inspect --engine googlereads one Sitemap live through the platform, using Google's API quota without spending URL Inspections. Bing Sitemap inspection reads dated stored evidence. Direct Google commands need Local mode. A flag applies to one command; the environment variable applies while it is set. Rungscdump auth status --jsonto see the active mode.- Most commands accept
--quietand--jsonfor scripts. Thequerycommand uses--format jsoninstead.
Use query --profile for query timings. Use --profile <name> to select a credential profile.
Numeric flags reject fractions, negative counts, and text suffixes.
Saved config rejects invalid values and unknown keys. If parsing fails, fix the reported file.