Check your sitemaps' errors and warnings from the terminal

By

Updated

List every sitemap Google has for your site, read its error and warning counts, and see which ones are still pending, with the searchglass CLI.

You changed how your site builds its sitemap, or you moved to a new framework, and now you want to know if Google is happy with it. The usual answer is to open Search Console, pick the property, open Sitemaps and squint at the Status column. Do that for three sites and it’s a chore.

Searchglass is a command-line tool that reads Google Search Console. Its sitemaps command prints the same sitemap report as JSON: every sitemap Google knows about, when Google last downloaded it, and how many errors and warnings it found. Add a short jq filter and you get a one-line answer per site.

At the end you’ll have a command that lists your sitemaps, a filter that shows only the broken ones, and a check that exits with an error when something needs fixing. That last part is what makes it useful in a weekly script or in a coding agent’s hands.

One limit up front: Searchglass only reads. It can’t submit or delete a sitemap. That stays a button in Search Console.

What you need

Searchglass runs on macOS or Linux, with Node.js 22 or later installed separately, and it needs a Google OAuth setup. It has no npm dependencies and no Mac app.

To get it, download the ZIP and the SHA256SUMS file from your Polar receipt. In the download folder, verify the ZIP with shasum -a 256 -c SHA256SUMS on macOS, or sha256sum -c SHA256SUMS on Linux. Unzip it, open a terminal in the unzipped folder, and run the installer:

./install.sh

The installer copies the files into ~/.local/share/searchglass/ and links the command at ~/.local/bin/searchglass. If your shell says “command not found”, add ~/.local/bin to your PATH.

You also need a Google Cloud project with the Search Console API enabled, and an OAuth client of type Desktop app. A Web application client won’t work. The Searchglass docs walk through those console screens. Your Google account must have access to the Search Console properties you want to read.

Then sign in once with the client JSON you downloaded:

searchglass login --client ~/Downloads/google-desktop-client.json

For the preflight check, confirm the version and that Google answers:

searchglass --version
searchglass auth status --check
searchglass 2.0.0

auth status --check prints JSON with "connected": true and "verified": true when the login works. The site names in this tutorial, like hostingpicker.dev, are examples. Use your own.

Find the property name Searchglass expects

Every sitemap belongs to a Search Console property, and Searchglass needs that property’s exact name in --site. This trips people up because Google has two kinds of property. A domain property is written sc-domain:hostingpicker.dev. A URL-prefix property is written https://hostingpicker.dev/, with the protocol and the trailing slash. They’re different properties, with different sitemap lists, even for the same site. If you type the name from memory, you’ll often pass something Google doesn’t recognize. So start by asking for the list:

searchglass sites

The output is JSON, with one entry per property your account can read. Each entry has a siteUrl and a permissionLevel. Copy the siteUrl as is.

To check a single property and your access level on it, pass --site:

searchglass sites --site https://hostingpicker.dev/

Example 3: a property name Searchglass rejects. Say you type the bare domain:

searchglass sitemaps --site hostingpicker.dev
{"error":{"message":"Invalid --site. Use sc-domain:example.com or https://example.com/."}}

Searchglass checks the shape of the name before it calls Google. Errors go to stderr as JSON and the command exits with status 1. The fix is the name from searchglass sites, here https://hostingpicker.dev/. If you forget --site entirely, you get a different message:

{"error":{"message":"Provide --site exactly as returned by searchglass sites, for example sc-domain:example.com."}}

List every sitemap Google knows about

The Search Console website shows the sitemaps you submitted, plus a status for each one. The API behind it returns the same list, and searchglass sitemaps prints it. This is the step that tells you what Google is working from. That matters more than what your site currently serves. If your build renamed sitemap.xml to sitemap-index.xml, Google may still be reading the old file, and its errors stay in the report until you deal with it. Without this list you’re guessing which file Google means when it reports a problem.

searchglass sitemaps --site https://hostingpicker.dev/

If you’d rather click, this is the same list as the Sitemaps report in Search Console, under Indexing, where each submitted sitemap has its type, status and the date Google last read it.

The response is an object with a sitemap array. Google’s Sitemaps API reference documents each entry with this shape:

{
  "path": string,
  "lastSubmitted": datetime,
  "isPending": boolean,
  "isSitemapsIndex": boolean,
  "type": string,
  "lastDownloaded": datetime,
  "warnings": long,
  "errors": long,
  "contents": [
    {
      "type": string,
      "submitted": long,
      "indexed": long
    }
  ]
}

Here’s what each field tells you:

  • path is the sitemap’s URL.
  • lastSubmitted is when someone submitted it, and lastDownloaded is when Google last fetched it.
  • isPending is true when Google hasn’t processed it yet.
  • isSitemapsIndex is true for a file that lists other sitemaps.
  • type is the format, such as sitemap, rssFeed, atomFeed or urlList.
  • errors and warnings are counts. Google describes warnings as generally non-critical issues with URLs in the sitemap.
  • contents breaks the file down by content type, like web, image or video. submitted is how many URLs of that type it lists.

Google marks contents[].indexed as deprecated, so don’t build anything on it. To see which pages made it into the index, inspect them one at a time, as in checking whether Google has indexed a page. The inspection also tells you which sitemap Google found the page in:

Terminal running searchglass inspect for https://trailheadnotes.com/gear/ultralight-tents/: the JSON result has verdict PASS, coverageState Submitted and indexed, the last crawl time, the Google and user canonical URLs, and a sitemap array with https://trailheadnotes.com/sitemap-0.xml

Read the error and warning counts

Raw JSON is fine for one sitemap. For a site with five, or for three sites, you want a table you can read at a glance. Since Searchglass prints plain JSON on stdout, you can save it to a file and point jq at it. If jq is new to you, the jq command covers the basics. The filters below pull out the path, the two counts and the last download time. They use // 0 because a pending sitemap may not have every field yet. Without that fallback, a missing field shows up as null and breaks the number comparisons in the next filter.

Example 1: the main path, a site with one broken sitemap. Save the list, then print a table. The values below come from an example file shaped like Google’s response, not from a real property:

searchglass sitemaps --site https://hostingpicker.dev/ > sitemaps.json
jq -r '.sitemap[] | [.path, (.errors // 0), (.warnings // 0), (.lastDownloaded // "never")] | @tsv' sitemaps.json
https://hostingpicker.dev/sitemap-index.xml	0	0	2026-11-10T21:03:52.000Z
https://hostingpicker.dev/sitemap.xml	1	0	2026-11-09T04:27:45.000Z
https://hostingpicker.dev/blog/rss.xml	0	0	never

Each row is path, errors, warnings and last download. The index is clean. The old sitemap.xml has one error. The RSS feed has never been downloaded, which usually means it’s still pending.

To print only the sitemaps with a problem, filter on the counts:

jq '[.sitemap[] | select((.errors // 0 | tonumber) > 0 or (.warnings // 0 | tonumber) > 0) | {path, errors, warnings}]' sitemaps.json
[
  {
    "path": "https://hostingpicker.dev/sitemap.xml",
    "errors": "1",
    "warnings": "0"
  }
]

Google documents the counts as long. The example file stores them as quoted strings, and tonumber handles them either way, so the filter works on both.

Here are the same two filters on trailheadnotes.com, a made-up hiking blog I use for screenshots. It has two sitemaps, and the routes one has 2 warnings:

Terminal in the trailhead project: searchglass sitemaps saves the list for sc-domain:trailheadnotes.com to sitemaps.json, the jq table prints sitemap-index.xml with 0 errors and 0 warnings and sitemap-routes.xml with 0 errors and 2 warnings, each with its last download time, and the second jq filter prints only sitemap-routes.xml with errors "0" and warnings "2"

And to list what Google hasn’t processed yet:

jq -r '.sitemap[] | select(.isPending) | .path' sitemaps.json
https://hostingpicker.dev/blog/rss.xml

The counts tell you that something is wrong, not what. The API has no field for the error messages. For those, open the property’s Sitemaps report in Search Console and click the sitemap’s row. Google’s Sitemaps report help lists the errors you can find there, like “URL not allowed” and “Invalid date”.

Look inside a sitemap index

Many sites publish a sitemap index: one file that points to several smaller sitemaps. Others serve a single file, like a dynamic sitemap.xml in Astro SSR. With an index, you usually submit only the index. When the index reports a problem, the useful question is which child file has it, because that’s the file you’ll fix. The plain sitemaps command lists what was submitted, so the children don’t appear on their own. Searchglass has two flags for going one level deeper.

Reading sitemaps with SearchglassStart by listing a property's submitted sitemaps. If an entry is a sitemap index, list its children with --index. Read a single sitemap with --sitemap. Both flags can't be used together.YesNoYesNosearchglass sitemaps--siteisSitemapsIndex?sitemaps --site--index URLsitemaps --site--sitemap URLErrors or warnings?Open the Sitemapsreport for themessagesDone

Example 2: an index instead of a flat list. Pass the index URL with --index to list its children:

searchglass sitemaps --site https://hostingpicker.dev/ --index https://hostingpicker.dev/sitemap-index.xml

The response has the same sitemap array as before, but each entry is now a child of that index, with its own errors, warnings and lastDownloaded. The jq filters from the previous section work on it unchanged, so you can save this output to a file and run the same table.

To read one sitemap by its URL, use --sitemap:

searchglass sitemaps --site https://hostingpicker.dev/ --sitemap https://hostingpicker.dev/sitemap.xml

Google’s API returns that single sitemap entry, with the fields described above. Use it when you only care about one file, like after a fix.

The two flags don’t mix. Searchglass refuses before it calls Google:

{"error":{"message":"Use either --sitemap or --index."}}

Both flags also need a full URL. A relative path like /sitemap.xml fails with this:

{"error":{"message":"Provide a fully qualified HTTP or HTTPS URL."}}

Fix the sitemap and check again

Once you know which file has errors, the fix happens in your site, not in Searchglass. Open the Search Console report for the error message, fix the generator or the file, and deploy. Then you need to know when Google has seen the new version. This is where lastDownloaded earns its place. If it’s older than your deploy, the counts you’re reading still describe the old file. Google re-reads sitemaps on its own schedule, so a clean deploy doesn’t show up right away. Without checking this field, you could decide your fix didn’t work when Google hasn’t looked yet.

searchglass sitemaps --site https://hostingpicker.dev/ --sitemap https://hostingpicker.dev/sitemap.xml | jq '{lastDownloaded, errors, warnings}'

The output is one object with those three fields. Compare lastDownloaded with your deploy time.

Running the same command a second time is safe. Searchglass only reads, with the webmasters.readonly scope, so there’s nothing to undo. Each run gets a fresh access token from your saved login, and nothing about your property changes.

If you want Google to look sooner, Google’s help says you can resubmit after big changes. Searchglass can’t do that. Its docs say the CLI has no write commands for sitemap submission. Resubmit in the Sitemaps report in Search Console.

If the broken file is an old sitemap your site no longer serves, removing it from Search Console is also a website-only action. That one deletes the entry from the report, so make sure it’s the old file and not the one you rely on. To catch pages that still link to retired URLs, how to run SEO checks from the terminal covers a crawl-based check from your side, which complements Google’s view.

Run the check every week, or hand it to an agent

A sitemap usually breaks quietly: a deploy changes a date format, or a plugin update renames the file. You find out weeks later, when pages stop showing up. A small check that fails loudly fixes that. jq -e sets its exit status from the result: 0 when the filter returns true, 1 when it returns false. That turns the sitemap list into a pass or fail you can put in a script, a CI job or a reminder.

searchglass sitemaps --site https://hostingpicker.dev/ > sitemaps.json
jq -e '[.sitemap[] | (.errors // 0 | tonumber)] | add == 0' sitemaps.json

With the example file from earlier, one sitemap has an error, so this prints:

false

and exits with status 1. When every count is zero, it prints true and exits with 0.

Searchglass itself also signals failure: errors go to stderr as JSON, with a nonzero exit status. A script can tell a sign-in problem apart from a sitemap problem by checking which command failed.

If you work with a coding agent, install the bundled skill so the agent knows the commands:

searchglass skill install --target codex

Use --target claude for Claude Code or --target cursor for Cursor, then reload the agent. Reinstalling an identical skill is safe. Replacing a different one needs --force. After that you can ask the agent to list the sitemaps for a property, flag any with errors, and look at the generator code in your project for the cause. The agent never sees your refresh token. Each command gets a fresh access token on its own.

If something looks wrong

  • If you see Not signed in. Run searchglass login --client /absolute/path/client.json., you haven’t logged in on this machine yet, or SEARCHGLASS_CONFIG_DIR points to a different folder. Run searchglass login --client with your Desktop app client JSON.
  • If you see Google connection expired or was revoked. Run searchglass login to reconnect., run searchglass login again. While your Google OAuth app is in Testing, Google may expire refresh tokens after seven days.
  • If you see Search Console HTTP 403: followed by Google’s message, your account lacks access to that property, or the Search Console API isn’t enabled in the OAuth client’s project. Check both, then confirm the name with searchglass sites.
  • If the sitemap array is empty or missing a file you expect, you’re probably looking at the other property type. A sitemap submitted under sc-domain:hostingpicker.dev doesn’t show under https://hostingpicker.dev/. List both with searchglass sites.
  • If a child sitemap doesn’t appear in the plain list, it was submitted through an index. Use --index with the index URL.
  • If the counts haven’t changed after a fix, compare lastDownloaded with your deploy time. Google may not have re-read the file yet. Resubmit in Search Console if you need it sooner.
  • If you see Unknown option '--submit', that’s expected. Searchglass is read-only and has no submit or delete flags.
  • If a request fails with Google request timed out. Try again., Google didn’t answer within 30 seconds. Searchglass already retries rate limits and server errors up to three times, so wait a bit and run the command again.

Get Searchglass

Query Google Search Console performance, sitemaps and URL index status from your terminal or coding agent. Includes an installer, agent skill and full MIT source.

See Searchglass → · Read the docs · $20. See the app page for tax details, with full source code.

More tutorials for my apps →

Want me to talk about your product? You can sponsor this site.