Command reference
Every gsc command with its flags and examples, generated from the command tree.
Generated from the gsc command tree on main. The command guides explain when to use each group.
Global flags apply to every command.
--access-token string Use this OAuth access token (prefer GSC_ACCESS_TOKEN)
--credentials string Google credentials JSON: service account, authorized user, or external account (or GSC_CREDENTIALS)
--dry-run For write commands: print the request and send nothing
--no-input Never prompt or open a browser
-o, --output string Output format: table, json, yaml, csv (default "table")
--profile string Named profile (or GSC_PROFILE)
-q, --quiet Suppress informational stderr output
--read-only Block remote writes, local credential changes, and self-update
-s, --site string Property: sc-domain:example.com, https://www.example.com/, or a bare host (or GSC_SITE)
--timeout duration HTTP request timeout (default 30s)
-v, --verbose Log request method, URL, and status to stderr (never tokens or bodies)
-y, --yes Confirm destructive commands and updates without promptinggsc
Google Search Console from your terminal
Search performance, URL inspection, sitemaps, and properties from Google Search Console.
Run gsc auth login once; it opens your browser and remembers the login.
Data goes to stdout and diagnostics to stderr. --read-only blocks every write.
gsc [flags] -h, --help help for gscgsc api
Send an authenticated request to the Search Console API (escape hatch)
PATH is relative to https://searchconsole.googleapis.com and must already be URL-escaped. GET and the read-only POSTs (searchAnalytics/query, urlInspection/index:inspect) are reads; every other request is treated as a write: blocked by --read-only, printed instead of sent with --dry-run, and confirmed interactively (or with --yes) before it is sent.
gsc api METHOD PATH [flags] gsc api GET /webmasters/v3/sites
gsc api POST /webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query --data '{"startDate":"2026-09-01","endDate":"2026-09-30"}'
gsc api PUT /webmasters/v3/sites/sc-domain%3Aexample.com/sitemaps/https%3A%2F%2Fexample.com%2Fsitemap.xml --dry-run --data string JSON request body, @file, or - for stdin
-h, --help help for apigsc api methods
List every Search Console API method: HTTP verb, read or write effect, status, and the commands that call it
Offline: reads the method registry pinned to the vendored discovery snapshot. path is what gsc api takes; status is implemented, retired, or skipped (with a note saying why).
gsc api methods [flags] gsc api methods
gsc api methods -o json -h, --help help for methodsgsc auth
Log in, inspect credentials, and manage profiles
gsc auth [flags] -h, --help help for authgsc auth list
List saved profiles (no secrets)
gsc auth list [flags] gsc auth list
gsc auth list -o json -h, --help help for listgsc auth login
Sign in with Google (opens your browser) or save another credential type
With no flags, opens Google's consent page in your browser and saves the login in the OS keychain. Tokens refresh automatically afterwards. --no-browser prints a URL to approve on any device and asks you to paste the final redirected URL back. --service-account and --adc save non-interactive credentials for CI. See docs/auth.md for every method.
gsc auth login [flags] gsc auth login
gsc auth login --profile work --scope readonly
gsc auth login --no-browser
gsc auth login --client-secret-file client_secret.json
gsc auth login --profile ci --service-account key.json
gsc auth login --profile gcloud --adc --impersonate reporting@my-project.iam.gserviceaccount.com --adc Use Application Default Credentials (gcloud, workload identity federation, metadata server)
--client-secret-file string Use your own Desktop OAuth client (JSON from Google Cloud Console)
-h, --help help for login
--impersonate string With --adc: service account email to impersonate through IAM Credentials
--insecure-storage Store the login in a 0600 plaintext file instead of the OS keychain
--no-browser Headless login: approve on any device, then paste the redirected URL
--no-verify Skip listing properties after login (no API call)
--scope string Search Console access to request: full or readonly (default "full")
--service-account string Save a service account JSON key file for this profile
--subject string With --service-account: Workspace user to impersonate (domain-wide delegation)gsc auth logout
Remove a profile and its saved login from this machine
Deletes the profile and its stored token locally. --revoke also revokes access at Google, which signs this Google account out of every machine and profile that uses the same OAuth client project; it asks for confirmation unless --yes is given.
gsc auth logout [flags] gsc auth logout
gsc auth logout --profile work --revoke --yes -h, --help help for logout
--revoke Also revoke access at Google (signs out every machine using the same OAuth client)gsc auth status
Show which credential is in use, without revealing it
Reads local configuration only. --verify additionally lists properties with the credential (one API call).
gsc auth status [flags] gsc auth status
gsc auth status --verify -o json -h, --help help for status
--verify Check the credential by listing properties (one API call)gsc auth token
Print a fresh access token for debugging (keep it secret)
gsc auth token [flags] curl -H "Authorization: Bearer $(gsc auth token)" https://searchconsole.googleapis.com/webmasters/v3/sites
gsc auth token --profile ci -h, --help help for tokengsc auth use
Set the default profile
gsc auth use NAME [flags] gsc auth use work -h, --help help for usegsc commands
Describe every command, its flags, and whether it reads or writes (for agents)
Offline: lists every runnable command with its usage, flags and defaults, effect (read, remote_write, or local_write), whether it may prompt, the Search Console API methods it exists to call, and examples. Global flags are listed once. Use -o json for the full description. Some calls are incidental and not listed: a bare host given to -s, --verify, doctor --online, and login each list properties once (webmasters.sites.list).
gsc commands [flags] gsc commands
gsc commands -o json | jq -r '.commands[] | select(.effect != "read") | .command' -h, --help help for commandsgsc completion
Generate shell completion script
gsc completion [bash|zsh|fish|powershell] [flags] source <(gsc completion zsh)
gsc completion bash > /usr/local/etc/bash_completion.d/gsc
gsc completion fish > ~/.config/fish/completions/gsc.fish -h, --help help for completiongsc config
Inspect configuration and select profiles
gsc config [flags] -h, --help help for configgsc config list-profiles
List saved profiles (no secrets)
gsc config list-profiles [flags] gsc config list-profiles
gsc config list-profiles -o json -h, --help help for list-profilesgsc config show
Show which credential is in use, without revealing it
Reads local configuration only. --verify additionally lists properties with the credential (one API call).
gsc config show [flags] gsc config show
gsc config show --verify -o json -h, --help help for show
--verify Check the credential by listing properties (one API call)gsc config use-profile
Set the default profile
gsc config use-profile NAME [flags] gsc config use-profile work -h, --help help for use-profilegsc doctor
Check configuration, credentials, and PATH (local unless --online)
gsc doctor [flags] gsc doctor
gsc doctor --online -o json -h, --help help for doctor
--online Also call the API once to list propertiesgsc export
Export Search Analytics day by day to CSV or NDJSON files (resumable)
Splits the range into days, as Google's extraction guide recommends, fetches every exposed row for each day, and writes one file per day through a temp file and rename. manifest.json records finished days; rerun the same command to resume. Days after the latest final date, and days Google marks incomplete, are recorded as preliminary and re-fetched on resume. No automatic retries unless --retry is given.
gsc export [flags] gsc export --last 16m -d query -d page --out ./gsc-export
gsc export --start 2026-01-01 --end 2026-03-31 -d page --format ndjson --out ./q1 --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--data-state string final (default), all (includes preliminary data), or hourly_all
-d, --dimension strings Group by: date, hour, query, page, country, device, searchAppearance (repeat or comma list)
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
--format string File format: csv or ndjson (default "csv")
-h, --help help for export
--interval duration Minimum time between the start of one day and the next (a day's pages are fetched back to back) (default 250ms)
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--out string Output directory (created if missing)
--restart Discard a manifest written for a different request
--retry int Retry quota and server errors this many times per day, with backoff (default 0)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc freshness
Latest dates with final and with preliminary data
Two small date-grouped queries over the last 10 days: one for final data and one including preliminary data. Final data usually lags two to three days.
gsc freshness [flags] gsc freshness
gsc freshness --type discover -o json -h, --help help for freshness
--type string Search type (default web)gsc insights
Opportunities computed locally from explicit queries (thresholds are printed)
Each insight runs ordinary Search Analytics queries and computes the result locally. The thresholds used are printed on stderr and included in JSON output. Results reflect rows Google exposes; anonymized queries are never included.
gsc insights [flags] -h, --help help for insightsgsc insights cannibalization
Queries where two or more pages split the impressions
gsc insights cannibalization [flags] gsc insights cannibalization --last 3m
gsc insights cannibalization --min-share 0.2 --filter 'query ~ pricing' --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for cannibalization
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum queries to show (default 25)
--min-impressions float Minimum total impressions for a query (default 100)
--min-share float Minimum share of a query's impressions for a page to count as competing (default 0.1)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc insights decliners
Queries or pages that lost the most clicks versus the comparison period
gsc insights decliners [flags] gsc insights decliners --compare yoy
gsc insights decliners --by page --min-clicks 20 -o json --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--by string Compare queries or pages (default "query")
--compare string Comparison period: previous or yoy (default "previous")
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for decliners
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to show (default 50)
--min-clicks float Minimum clicks in the comparison period (default 5)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc insights lost-queries
Queries or pages returned in the comparison period but not now (no longer exposed)
gsc insights lost-queries [flags] gsc insights lost-queries --last 7d
gsc insights lost-queries --by page -o json --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--by string Compare queries or pages (default "query")
--compare string Comparison period: previous or yoy (default "previous")
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for lost-queries
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to show (default 50)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc insights low-ctr
Queries whose CTR is well below this site's median for the same position
gsc insights low-ctr [flags] gsc insights low-ctr
gsc insights low-ctr --factor 0.4 --min-impressions 200 -o json --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--factor float Flag queries with CTR below this fraction of the bucket median (default 0.5)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for low-ctr
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to show (default 50)
--min-impressions float Minimum impressions for a query to count (default 100)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc insights new-queries
Queries or pages returned now but not in the comparison period (newly exposed)
gsc insights new-queries [flags] gsc insights new-queries --last 7d
gsc insights new-queries --by page --compare yoy --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--by string Compare queries or pages (default "query")
--compare string Comparison period: previous or yoy (default "previous")
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for new-queries
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to show (default 50)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc insights striking-distance
Queries ranking just off the top (average position 4 to 20) with real impressions
gsc insights striking-distance [flags] gsc insights striking-distance
gsc insights striking-distance --min-impressions 500 --max-position 15 -o json --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for striking-distance
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to show (default 50)
--max-position float Highest average position to include (default 20)
--min-impressions float Minimum impressions in the period (default 100)
--min-position float Lowest average position to include (default 4)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc inspect
URL Inspection: Google's indexed view of URLs (not a live test)
Calls the URL Inspection API for each URL. It reports the indexed version only: there is no live test and no request-indexing in the API. Google allows 2,000 inspections per property per day and 600 per minute; batches are paced below that and stop cleanly when a quota is reached.
gsc inspect [URL...] [flags] gsc inspect https://www.example.com/pricing
gsc inspect --file urls.txt -o json
cat urls.txt | gsc inspect --file - --max 200 --file string Read URLs from a file, one per line (- for stdin)
-h, --help help for inspect
--interval duration Pause between inspections (stays under 600 per minute) (default 120ms)
--language string BCP 47 language for issue messages (default en-US)
--max int Inspect at most this many URLs (the per-property daily quota is 2,000) (default 2000)gsc login
Alias of auth login
With no flags, opens Google's consent page in your browser and saves the login in the OS keychain. Tokens refresh automatically afterwards. --no-browser prints a URL to approve on any device and asks you to paste the final redirected URL back. --service-account and --adc save non-interactive credentials for CI. See docs/auth.md for every method.
gsc login [flags] gsc login
gsc login --no-browser
gsc login --profile work --scope readonly --adc Use Application Default Credentials (gcloud, workload identity federation, metadata server)
--client-secret-file string Use your own Desktop OAuth client (JSON from Google Cloud Console)
-h, --help help for login
--impersonate string With --adc: service account email to impersonate through IAM Credentials
--insecure-storage Store the login in a 0600 plaintext file instead of the OS keychain
--no-browser Headless login: approve on any device, then paste the redirected URL
--no-verify Skip listing properties after login (no API call)
--scope string Search Console access to request: full or readonly (default "full")
--service-account string Save a service account JSON key file for this profile
--subject string With --service-account: Workspace user to impersonate (domain-wide delegation)gsc performance
Totals for a period: clicks, impressions, CTR, average position
A query with no dimensions, so totals match the Performance report chart (anonymized queries included).
gsc performance [flags] gsc performance --last 28d --compare previous
gsc performance --type discover --last 3m -o json --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--compare string Also query a comparison period: previous or yoy
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for performance
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc query
Search Analytics with every API option (dimensions, filters, types, data state)
Runs searchAnalytics.query. Without dates it covers the last 28 days ending at the latest day with data (one small extra request finds that day; pass --end to skip it). Results are sorted by clicks by Google. "complete" in the output means every row Google exposes was fetched; anonymized queries are never included.
gsc query [flags] gsc query -s sc-domain:example.com -d query -d page --limit 5000 -o csv
gsc query --last 3m -d date --filter 'country = ind' --filter 'query ~ shoes'
gsc query -d hour --data-state hourly_all --last 2d -o json
gsc query -d query --compare previous --limit 500 --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--all Fetch every row Google exposes for the query
--compare string Also query a comparison period: previous or yoy
--data-state string final (default), all (includes preliminary data), or hourly_all
-d, --dimension strings Group by: date, hour, query, page, country, device, searchAppearance (repeat or comma list)
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for query
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to return (pages of up to 25,000 are fetched) (default 1000)
--print-request Print the request body and send nothing
--raw Print the API response unchanged (single page, no --all or --compare)
--request-file string JSON request body to start from (flags override its fields; - for stdin)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc sitemaps
List, inspect, submit, and delete sitemaps for a property
gsc sitemaps [flags] -h, --help help for sitemapsgsc sitemaps delete
Delete a sitemap from the report (Google may still crawl it)
gsc sitemaps delete SITEMAP_URL [flags] gsc sitemaps delete https://www.example.com/old-sitemap.xml --yes -h, --help help for deletegsc sitemaps get
Show one sitemap's status, errors, and warnings
gsc sitemaps get SITEMAP_URL [flags] gsc sitemaps get https://www.example.com/sitemap.xml -h, --help help for getgsc sitemaps list
List submitted sitemaps
gsc sitemaps list [flags] gsc sitemaps list
gsc sitemaps list --index https://www.example.com/sitemap_index.xml -o json -h, --help help for list
--index string Only sitemaps listed in this sitemap index URLgsc sitemaps submit
Submit a sitemap URL for the property
gsc sitemaps submit SITEMAP_URL [flags] gsc sitemaps submit https://www.example.com/sitemap.xml
gsc sitemaps submit https://www.example.com/sitemap.xml --dry-run -h, --help help for submitgsc sites
List and manage Search Console properties
gsc sites [flags] -h, --help help for sitesgsc sites add
Add a property to your Search Console list (does not verify ownership)
SITE must be exact: sc-domain:example.com or a URL-prefix such as https://www.example.com/. Adding a property does not verify it. A URL-prefix inside a domain property you already own is verified at once; otherwise complete verification in Search Console. The output reports the resulting permission.
gsc sites add SITE [flags] gsc sites add https://blog.example.com/
gsc sites add sc-domain:example.org --dry-run -h, --help help for addgsc sites get
Show one property (default: the profile's site)
gsc sites get [SITE] [flags] gsc sites get
gsc sites get https://www.example.com/ -o json -h, --help help for getgsc sites list
List properties you can access and your permission level
gsc sites list [flags] gsc sites list
gsc sites list -o json -h, --help help for listgsc sites remove
Remove a property from your Search Console list
gsc sites remove SITE [flags] gsc sites remove https://old.example.com/ --yes -h, --help help for removegsc sites use
Set the profile's default site
Exact property identifiers are saved without a network call; a bare host is resolved with one sites.list call.
gsc sites use SITE [flags] gsc sites use sc-domain:example.com
gsc sites use www.example.com -h, --help help for usegsc status
Alias of auth status
Reads local configuration only. --verify additionally lists properties with the credential (one API call).
gsc status [flags] gsc status
gsc status --verify -h, --help help for status
--verify Check the credential by listing properties (one API call)gsc top
Top queries, pages, countries, devices, or search appearances
gsc top [flags] -h, --help help for topgsc top appearance
Search appearance types (filter on one with --filter 'searchAppearance = VALUE' in gsc query)
gsc top appearance [flags] gsc top appearance --last 3m -o json --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--all Fetch every row Google exposes for the query
--compare string Also query a comparison period: previous or yoy
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for appearance
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to return (pages of up to 25,000 are fetched) (default 25)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc top countries
Clicks and impressions by country (ISO 3166-1 alpha-3)
gsc top countries [flags] gsc top countries --last 3m --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--all Fetch every row Google exposes for the query
--compare string Also query a comparison period: previous or yoy
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for countries
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to return (pages of up to 25,000 are fetched) (default 25)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc top devices
Clicks and impressions by device
gsc top devices [flags] gsc top devices --compare yoy --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--all Fetch every row Google exposes for the query
--compare string Also query a comparison period: previous or yoy
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for devices
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to return (pages of up to 25,000 are fetched) (default 25)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc top pages
Top pages by clicks
gsc top pages [flags] gsc top pages --filter 'page ~ /blog/'
gsc top pages --all -o csv > pages.csv --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--all Fetch every row Google exposes for the query
--compare string Also query a comparison period: previous or yoy
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for pages
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to return (pages of up to 25,000 are fetched) (default 25)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc top queries
Top search queries by clicks
gsc top queries [flags] gsc top queries --last 7d
gsc top queries --compare previous --limit 50 -o json --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--all Fetch every row Google exposes for the query
--compare string Also query a comparison period: previous or yoy
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for queries
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--limit int Maximum rows to return (pages of up to 25,000 are fetched) (default 25)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc trend
Clicks, impressions, CTR, and position over time
Groups by date (default), hour (last 10 days, preliminary data), ISO week, or calendar month. Week and month totals are rolled up locally from daily rows: clicks and impressions summed; CTR recomputed from the sums; position weighted by impressions.
gsc trend [flags] gsc trend --last 3m --by week
gsc trend --by hour --last 2d
gsc trend --last 16m --by month --filter 'page ~ /blog/' --aggregation string auto, byPage, byProperty, or byNewsShowcasePanel
--by string Granularity: date, hour, week, or month (default "date")
--data-state string final (default), all (includes preliminary data), or hourly_all
--end string End date YYYY-MM-DD (Pacific Time, inclusive)
--filter stringArray Filter 'DIM OP VALUE'; OP is = != ~ !~ =~ !=~ (contains/regex); repeat to AND
-h, --help help for trend
--last string Window ending at the latest available date: 7d, 28d, 4w, 3m, 16m (default 28d)
--start string Start date YYYY-MM-DD (Pacific Time, inclusive)
--type string Search type: web (default), image, video, news, discover, googleNewsgsc update
Update gsc to the latest release (SHA-256 verified)
Downloads the latest GitHub release for this OS and architecture, verifies it against the release's checksums.txt, and replaces the running gsc executable. Works on macOS, Linux, and Windows; on Windows the old executable is renamed to gsc.exe.old and deleted on a later run.
Asks "Update now? [Y/n]" when stdin is a terminal; --yes skips the question, and --no-input requires --yes. --check only reports the current and latest versions. A gsc in a Go bin directory ($GOBIN, $GOPATH/bin, or ~/go/bin) is not replaced: rebuild it from your checkout instead. --read-only blocks installing but allows --check.
Update notice: in an interactive terminal, gsc checks the github.com releases page (not the GitHub API, so its rate limit never applies) for a new release at most once a day and, after a command's output, prints a notice on stderr. The command that runs the day's check waits up to 1 second after its output for the answer; other commands never wait. gsc update and update --check store their result in the same cache. It never checks when stderr is not a terminal, when CI is set, with --quiet, or when GSC_NO_UPDATE_NOTIFIER or NO_UPDATE_NOTIFIER is set (to anything).
gsc update [flags] gsc update --check
gsc update
gsc update --yes --no-input --check Only report the current and latest versions (always checks the github.com releases page)
-h, --help help for updategsc version
Print build information
Prints the version, commit, build date, and whether a built-in OAuth client is present. latest and update_available come from the last release check (see gsc update --help) and appear only when one is cached; version never uses the network.
gsc version [flags] gsc version
gsc version -o json -h, --help help for version