SEOmatic CLI: Audit Any URL from Your Terminal

Two commands need no account and no key. Copy any line and run it.

# 1. Audit any URL. No account.
npx seomatic audit https://example.com

# 2. Find crawl-budget waste in a server log. No account.
npx seomatic logs /var/log/nginx/access.log

# 3. Sign in (creates a free account if you have none), then read
#    your own Search Console data.
npx seomatic login
npx seomatic gsc top-queries --days 28

seomatic loginopens your browser on SEOmatic's approval screen, the same one Claude and ChatGPT use. Pick the workspace, approve, and the key comes back to the terminal. Nothing to copy from the dashboard.

• The key is kept in the macOS Keychain, the Linux keyring, or encrypted with Windows DPAPI; where none is available, in ~/.config/seomatic/credentials.json, readable only by you. It is valid for one year.
• Each computer gets its own key. It shows in Settings > AI Agents > API Keys under your computer's name. seomatic logout revokes it.
• Choosing a workspace needs the admin role there, the same right as creating a key in Settings.
• Over SSH or on a server, seomatic login --device shows a short code to approve from any browser, on any device (chosen automatically when there is no local browser).
• In CI, set SEOMATIC_API_KEY to a key from Settings instead.

npx seomatic login            # opens the browser
npx seomatic login --device   # SSH / servers: approve a code anywhere
npx seomatic me               # workspace, scopes, Search Console state
npx seomatic logout           # revoke and forget

# Tab completion (needs a global install: npm i -g seomatic)
seomatic completion zsh > "${fpath[1]}/_seomatic"

# CI: a key from Settings > AI Agents > API Keys
export SEOMATIC_API_KEY=smk_live_...

Several client workspaces? Give each a profile: seomatic login --profile acme, then add --profile acme to any command. The key is only ever sent over https.

Key order: --key, then SEOMATIC_API_KEY, then your login.

seomatic audit fetches one URL and runs 10 checks (11 with a robots.txt), covering classic SEO and whether an AI answer engine can read the page.

reachabletitlemeta_descriptioncanonicalh1json_ldrobots_txtai_bots_allowedsitemapllms_txtsecurity_txt

npx seomatic audit https://example.com --json

{
  "url": "https://example.com",
  "score": 30,
  "passed": 3,
  "total": 10,
  "checks": [{ "id": "reachable", "ok": true, "detail": "HTTP 200 in 133ms" }]
}

score is passed over total as a percentage. The command exits 0 even when checks fail, because a failing check is a finding rather than a CLI error. Branch on the score, not the exit code.

The split that matters in CI: 1 means the call was wrong, 2 means we could not complete it. Retry on 2 only.

With --json, stdout carries exactly one JSON value: the result, or on failure an error object. Progress goes to stderr. Without it, errors go to stderr.

npx seomatic audit https://example.com --json | jq .score

Branch on code and status; error is a sentence for people and may change wording.

{
  "error": "Free monthly limit reached (5 questions). Upgrade ...",
  "status": 402,
  "code": "FREE_QUOTA_EXCEEDED",
  "upgrade_url": "https://app.seomatic.ai/..."
}

Each of these is a complete, runnable snippet.

# Fail a build when a page regresses
score=$(npx seomatic audit "$URL" --json | jq -r .score)
[ "$score" -ge 80 ] || { echo "SEO score $score < 80"; exit 1; }

# List every check that failed
npx seomatic audit "$URL" --json | jq -r '.checks[] | select(.ok|not) | .id'

# Find AI crawlers wasting budget on errors
npx seomatic logs access.log --json   | jq -r '.bots[] | select(.isAiBot and .wastedCrawlPct > 20)
           | "(.bot) (.wastedCrawlPct)% wasted"'

# Retry only on runtime failures, never on your own bad call
for i in 1 2 3; do
  npx seomatic me --json && break
  [ $? -eq 2 ] || break
  sleep $((i * 2))
done

seomatic me --json is the fastest first report to include when asking for help.