Run a scan

What this guide covers

Oobee scans a website, a sitemap or local files and writes a report to a results folder. This guide shows how to choose a scan type and run it with command-line options or the interactive prompts. It does not cover custom flow scans, scans behind a login, or PDF and local file scans, which have their own guides.

Prerequisites

Oobee installed. Refer to Install the portable Oobee or Install Oobee manually.
A terminal open in the oobee folder.
The URL of a site or sitemap you are allowed to scan.
Your name and email address for the -k option, unless you set OOBEE_DISABLE_TELEMETRY=1.

Scan types

Oobee has five scan types. Pass the name or its number to -c.

Type	`-c` value	What it scans
Sitemap	`sitemap` or `1`	The URLs listed in a sitemap
Website	`website` or `2`	A start page and the pages it links to
Custom flow	`custom` or `3`	Pages you open yourself in a browser. Refer to Scan a user flow with custom flow
Intelligent	`intelligent` or `4`	The sitemap found through `robots.txt`, then links to pages the sitemap misses
Local file	`localfile` or `5`	An HTML, PDF, sitemap XML or TXT file on your computer. Refer to Scan PDFs and local files

Use Intelligent for the most complete coverage of a live site. Refer to How Oobee scans for how each type finds pages.

Step 1: Run a scan from the command line

Run npm run cli -- with a scan type, a URL and your details:

npm run cli -- -c intelligent -u <WEBSITE_URL> -k "<YOUR_NAME>:<YOUR_EMAIL>"

Oobee checks the URL, prints “Starting scan…”, then scans up to 100 pages. On Windows PowerShell, add a second -- after npm run cli -- if options are not recognised.

Wrap a URL that contains a query string in single quotes. A sitemap scan takes the sitemap URL:

npm run cli -- -c sitemap -u <SITEMAP_URL> -k "<YOUR_NAME>:<YOUR_EMAIL>"

Step 2: Choose the device to scan as

By default, Oobee scans as a desktop browser. Use one of two options. They cannot be used together:

-d — a device name. Desktop, Mobile (iPhone 11 viewport) or any Playwright device name, for example 'iPad (gen 7) landscape'.
-w — a viewport width in pixels, from 320 to 1080.

npm run cli -- -c website -u <WEBSITE_URL> -d 'iPad (gen 7) landscape' -k "<YOUR_NAME>:<YOUR_EMAIL>"

Wrap a device name that contains brackets in single quotes. For the full device list, refer to CLI options, environment variables and error codes.

Step 3: Limit the pages and time

Set limits to keep a scan short or to match the size of the site:

Option	Effect
`-p <NUMBER>`	Stop after this many pages are scanned. The default is 100. Not available for custom flow scans.
`-l <SECONDS>`	Stop after this many seconds. The default is 0, which means no limit.
`-s same-hostname`	Follow links only on the exact hostname of the start URL. The default for website scans is `same-domain`, which includes subdomains.

npm run cli -- -c website -u <WEBSITE_URL> -p 10 -l 600 -s same-hostname -k "<YOUR_NAME>:<YOUR_EMAIL>"

The -p limit counts successfully scanned pages only. Pages that fail do not use up the limit.

Step 4: Save the results to a zip file or a folder

Add -o to also write the results to a zip file, and -e to choose where the scan folder is created. The -e folder must already exist, and Oobee creates the scan folder inside it. Oobee checks the path exactly as you type it, so a relative path is relative to the folder where you run the scan. The CLI help says the path is relative to your home directory, which is out of date.

npm run cli -- -c website -u <WEBSITE_URL> -o oobee-scan-results.zip -k "<YOUR_NAME>:<YOUR_EMAIL>"

When the scan finishes, Oobee writes a folder of reports inside results in your current folder. Refer to Read and export scan reports to work with them.

Run a scan with the interactive prompts

To answer prompts instead of typing options, run:

npm start

Oobee asks for your name and email address the first time, then asks in turn:

“What would you like to scan?” Choose Sitemap, Website, Custom, Intelligent or Localfile.
“Do you want Oobee to run in the background?” Answer Yes for a headless scan, or No to watch the browser.
“Which screen size would you like to scan?” Choose Desktop, Mobile or Custom. Custom offers iPhone 11, Samsung Galaxy S9+ or a viewport width.
The URL, sitemap or file path to scan.

The interactive mode scans HTML and PDF files and uses the default limits. To set page limits, a time limit, a proxy or other options, use the command line.

Constraints and limitations

Constraint	Detail
Device options	`-d` and `-w` cannot be used together.
Viewport width	Must be between 320 and 1080 pixels.
Page limit	`-p` is not available for custom flow scans.
Strategy `ignore`	`-s ignore` is valid only for sitemap scans, and is the default for them.
Strategy availability	`-s` is not available for local file scans.
Name and email	`-k` is required unless `OOBEE_DISABLE_TELEMETRY` is set to `1`, `true` or `yes`.
Scan results location	Results go to `results` in the folder where you run the scan, or to a scan folder inside the `-e` folder. If the default `results` folder is not writable, Oobee writes to an `Oobee` folder in your Documents folder (Windows and macOS) or home folder (Linux). The fallback does not apply to `-e`.

Scan pages behind a login — send credentials or cookies with a scan.
Configure a proxy — scan through a proxy server.
CLI options, environment variables and error codes — every option and default.
Troubleshooting — fix a scan that fails or skips pages.

Scanning

Scan a user flow with custom flow