CLI

The Consuela CLI is a standalone binary that runs the same crawler and the same issue audit as the desktop app, with no GUI and no dependencies. It is built for headless environments: CI pipelines, shell scripts, scheduled jobs, and anywhere a crawl needs to run unattended and report back through an exit code.

Usage

Point the binary at a URL and it crawls immediately:

consuela https://example.com

Bare hostnames are accepted — consuela example.com is treated as https://example.com. By default the crawl stops at 500 URLs, runs 5 concurrent requests at 2 requests per second, and respects robots.txt. All of these are tuneable:

consuela https://example.com \
  --max-urls 20000 \
  --concurrency 10 \
  --rate 5 \
  --max-depth 15

Pass --include and --exclude (repeatable) to scope the crawl with regexes, and --no-robots to skip robots rules when you need the full picture. Use --include-subdomains to treat subdomains as internal (e.g. blog.example.com when crawling example.com), and --quiet to suppress progress output on stderr, keeping stdout clean for piping.

Results go to stdout by default. --output report.json writes them to a file instead.

Exporting

The CLI can export crawl data in two additional formats beyond the report output: CSV and XML sitemaps. Both run after the crawl completes and can be combined with any --format for the main report.

consuela https://example.com \
  --export-csv results.csv \
  --export-sitemap sitemap.xml

--export-csv writes one row per crawled page with the same columns as the desktop app's "Export all" function — status code, title, meta description, word count, and every field the issue audit inspects. The file is ready for a spreadsheet or a data pipeline.

--export-sitemap generates an XML sitemap from what the crawler actually found. This is useful for producing a sitemap from live crawl data rather than what the site's existing sitemap claims.

Pass --db crawl.db alongside the exports to keep the full crawl database as well. With --store-html, the database also includes each page's raw HTML.

Output formats

Choose a format with --format:

Format	Flag	Purpose
Text	`--format text`	Human-readable summary grouped by check. This is the default.
JSON	`--format json`	Machine-readable object with crawl stats and per-check issue counts, suitable for scripting and dashboards.
JUnit XML	`--format junit`	One `<testcase>` per check. Most CI systems consume JUnit natively, so this gives you a test report tab with no extra tooling.

In JUnit mode, checks that breach the --fail-on threshold appear as <failure> elements; checks with findings below the threshold are recorded as <skipped>, so the CI report and the exit code always agree.

Exit codes

Code	Meaning
`0`	Crawl completed and no issues at or above the `--fail-on` threshold were found.
`1`	Issues found at or above the threshold. The report lists them; the build should stop.
`2`	The crawl itself failed — bad URL, network error, storage error, or nothing was fetched. This is distinct from "issues found" because it means no audit ran at all.

By default --fail-on is none, so the CLI always exits 0 on a successful crawl regardless of findings. Set it to warning or critical to gate a pipeline:

# Fail the build on warnings or worse
consuela https://staging.example.com --fail-on warning --format junit

# Only block on critical issues
consuela https://staging.example.com --fail-on critical

Ordering is by seriousness: --fail-on warning also fails on criticals, and --fail-on notice fails on everything.

Persisting results

Pass --db to write the crawl to a SQLite file. Without it, results live in memory for the duration of the run and are discarded after the report is written.

consuela https://example.com --db example.db

The database uses the same schema as the desktop app. You can open a CLI database in the desktop app to browse the results visually, or query it directly with any SQLite client.

When to use the CLI

The CLI and the desktop app run the same crawler engine and evaluate every page against the same set of issue rules. The difference is the surface: the desktop app is interactive, with analysis panels, filtering, and visual drill-downs; the CLI is non-interactive, with structured output and exit codes.

Reach for the CLI when the crawl should run without a person present:

CI gates that block a deploy when SEO regressions appear
Scheduled audits that feed a dashboard or alerting system
Shell scripts that crawl a list of domains in sequence
Build steps that produce a JUnit report alongside the test suite

Reach for the desktop app when you need to investigate: filter the results, walk redirect chains, inspect structured data, or compare two crawls side by side.