Command line (npm package)

@toolz-dev/aiscan is the AI Site Scanner as a command-line tool. Run npx @toolz-dev/aiscan example.com and it prints the grade, the score, a bar for each category and every failed check. Add --min-score to fail a CI build below a score, or --fix to get one prompt that fixes every failed check. It is MIT-licensed, has no dependencies, and its source is at github.com/Toolz-dev/aiscan.

The scan itself runs on Toolz.dev, not on your machine: the CLI sends the URL to the same HTTP endpoint the scanner page uses and prints what comes back, so the CLI and the website always agree.

How do I run it?

You need Node.js 18 or later. With no install:

npx @toolz-dev/aiscan example.com

To install it once and run it as aiscan:

npm i -g @toolz-dev/aiscan

aiscan example.com

Without npm, fetch the single file and pipe it into Node:

curl -fsSL https://toolz.dev/cli.cjs | node - example.com

https://toolz.dev/cli.cjs redirects to the published package file on unpkg (https://unpkg.com/@toolz-dev/aiscan/cli.cjs), so it always runs the latest release. -L in -fsSL is what makes curl follow that redirect.

What are the options?

Option	What it does
--site	Grade the whole site: up to 5 pages from the sitemap as well as the URL. See Page scan vs whole-site scan
--min-score <n>	Exit with code 1 when the score is below n (0 to 100). --min-score=85 works too
--fix	Print one agent-ready prompt that fixes every failed check, instead of the report
--json	Print the raw scan result as JSON, with a reportUrl field added
--no-color	Plain output. Setting the NO_COLOR environment variable does the same, and colour is off whenever output is not a terminal
-h, --help	Show the help
-v, --version	Show the version

The URL can be a domain or a full page URL. Only one URL per run; a second one is an error.

The CLI has no site-type or check filter: it always runs all 31 checks, the same as All Checks on the scanner page. Compare its score only with web scans run that way, since a content-site filter scores the same site differently (why).

What does the output look like?

The default report goes to standard output: the domain with its score and grade, the detected platform, one line per category with a 10-block bar and its score, then either "Every check passed." or "N checks failed" with each failed check's label and what was found. A whole-site scan adds a Pages graded list. The report link comes last, as Report: https://toolz.dev/ai-scan/r/<id>.

Progress ("Scanning example.com...") and errors go to standard error, so piping the output captures only the report. With --json or --fix, the progress line is not printed at all, which keeps the output clean to pipe:

npx @toolz-dev/aiscan example.com --fix | pbcopy
npx @toolz-dev/aiscan example.com --json > scan.json

The --fix prompt starts with the URL, the score and the grade, lists each failed check with what was found, the fix and a reference link where there is one, and ends with the command to re-check. If --json and --fix are both given, --json wins. Fixing issues with fix prompts covers how to use the prompt.

What do the exit codes mean?

Code	Meaning
0	The scan ran, and the score met --min-score (or no --min-score was given)
1	The score is below --min-score
2	Bad arguments: an unknown option, a missing URL, or a --min-score that is not a number from 0 to 100
3	The scan could not run: Toolz.dev was unreachable, the request was refused (for example, rate limited), or the site itself could not be loaded

When the score is below --min-score, the CLI prints the report first and then Score 72 is below --min-score 85. (with your numbers) to standard error.

How do I run it in CI?

Add a step that runs the CLI with --min-score. The job fails when the site scores lower. In GitHub Actions:

name: AI readiness
on:
  push:
    branches: [main]
  schedule:
    - cron: "0 6 * * 1"
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @toolz-dev/aiscan ${{ vars.SITE_URL }} --min-score 85

SITE_URL is a repository variable holding your domain. Scan the deployed site, not a preview that needs a login, and scan after the deploy step if the workflow also deploys. Pick a threshold a little under your current score so the job catches a drop without failing on noise such as a slow response time on one run.

Keep in mind the per-IP limit of 6 scans a minute on Toolz.dev (Public and private scans, limits and Pro). A 429 exits with code 3, not 1.

Are CLI scans public?

Yes, always. The CLI does not sign in, and private scans need a Toolz Pro account, so every CLI scan is stored as a public report and the domain's newest public scan is listed at /ai-scan/scans. If a report must stay out of that list, run the scan on the scanner page with a Pro account.

The CLI sends only the URL you give it. Privacy and what gets fetched covers what Toolz.dev then requests from the site.

Can I point it at another server?

Yes. Set TOOLZ_AISCAN_URL to the base URL of another Toolz.dev instance, such as a local development server; the default is https://toolz.dev:

TOOLZ_AISCAN_URL=http://localhost:5173 npx @toolz-dev/aiscan example.com

The report link then points at that host too.