MCPRemote MCP server for Cursor and Claude Code, on your existing API key→ Read the docs
QuikSEO.com
Sign inStart Free Audit

Documentation

SEO CLI: Check Build HTML Before You Deploy

The QuikSEO CLI checks the HTML files of a site build before you deploy it. It sends the pages to QuikSEO, prints every finding and site contract violation, and fails the build when it finds something new. It can also compare a preview with production and record each deploy.

Install and Authenticate

The CLI runs on Node.js 18 or newer and has no dependencies.

  1. Copy packages/cli from the QuikSEO repository into your project, or install it from your package registry.
  2. Create an API key on the Account > API page.
  3. Set it as the QUIKSEO_API_KEY environment variable, or pass --api-key.
  4. Add the website to your QuikSEO account; the CLI finds it by the host of --base-url, or by --website-id.

Check a Build

quikseo check dist --base-url https://example.com checks every HTML file in dist as the page it is served at. The HTML is evaluated and dropped; QuikSEO keeps only the findings, by URL and rule.

QUIKSEO_API_KEY=... npx quikseo check dist --base-url https://example.com --fail-on new --threshold error

How Files Map to URLs

index.html is its directory and other .html files lose the extension: dist/tools/index.html is /tools and dist/tools/qr.html is /tools/qr. Use --trailing-slash always for sites that serve /tools/. 404.html, 500.html and node_modules are skipped unless you pass your own --exclude patterns.

What Counts as New

A finding is new when the baseline does not have it. The baseline is the latest check of the baseline branch (--baseline-branch, by default the branch being built), or, before the first check, the issues open in monitoring. Every failure also shows the commit that introduced it: the first build of the uninterrupted run of builds that found it.

Exit Codes

  • 0: nothing blocks.
  • 1: findings block the build (new failures at or above the threshold with --fail-on new, every failure at or above it with --fail-on any).
  • 2: an error, such as a missing API key, a bad option or an unreachable API.

Checks of HTTP responses (status, redirects, headers, TLS) and of robots.txt need a live server, so they stay not checked in a build check.

Compare a Preview With Production

quikseo compare audits the same paths on a verified preview origin and on production and lists what the preview adds, fixes or changes in the head. Declare and verify the preview origin first on the website's Preview vs production page.

npx quikseo compare --base-url https://example.com --preview-origin https://preview.example.com --dir dist

Record a Deploy

quikseo deploy records the deployed commit and re-audits the website's monitored URLs at once. An issue those audits find, that no build check had found, is attributed to this deploy.

Keep the Contract in the Repository

When quikseo.config.json exists in the working directory, quikseo check applies it instead of the contract saved in QuikSEO; pass --config none to use the saved one. quikseo contract pull and quikseo contract push copy the contract between the repository and QuikSEO.

Options

Every option of quikseo check; run quikseo --help for the full list.

OptionMeaning
--base-urlAddress the build is served at.
--website-idThe website in QuikSEO, when the host does not identify it.
--formattext, json or github (workflow annotations; the default inside GitHub Actions).
--fail-onnew (default), any or none.
--thresholdLowest severity that blocks: critical, error (default), warning or info.
--commit, --branchDefault from the GitHub environment or from git.
--api-urlQuikSEO address, for a self-hosted instance.

Related Documentation