CLI Reference

Every flag, output format, and exit code the Consuela CLI accepts. For a higher-level introduction to the CLI and when to reach for it, see the CLI overview.

Usage

consuela <URL> [OPTIONS]

The URL is positional — it comes before any flags. Bare hostnames are accepted: consuela example.com is treated as consuela https://example.com.

consuela https://example.com
consuela example.com --max-urls 2000 --format json

Flags

Flag	Type	Default	Description
`<URL>`	string	—	The URL to crawl (positional, required). Bare hosts are auto-prefixed with `https://`.
`--max-urls`	integer	`500`	Maximum number of URLs to crawl before stopping.
`--max-depth`	integer	`10`	Maximum link depth from the start URL.
`--concurrency`	integer	`5`	Number of concurrent requests. Clamped to the range 1–50 ; values outside it are silently adjusted.
`--rate`	float	`2.0`	Maximum requests per second.
`--timeout`	integer	`30`	Per-request timeout in seconds.
`--user-agent`	string	built-in	Override the default User-Agent header. When unset, the crawler identifies itself with a built-in default.
`--include`	regex	—	Only crawl URLs matching this pattern. Repeatable ; multiple patterns are combined with OR.
`--exclude`	regex	—	Skip URLs matching this pattern. Repeatable. Applied after `--include`, so an excluded URL is skipped even if it matches an include pattern.
`--no-robots`	flag	`false`	Ignore `robots.txt` rules. Useful for auditing pages that are disallowed but still linked.
`--follow-external`	flag	`false`	Follow links to other domains. By default the crawl stays within the start URL's host.
`--include-subdomains`	flag	`false`	Treat subdomains as internal. When crawling `example.com`, links to `blog.example.com` are followed instead of being treated as external.
`--max-page-size`	integer	built-in	Maximum page size in bytes. Pages larger than this are skipped during the crawl.
`--store-html`	flag	`false`	Store each page's HTML in the database. Requires `--db`. Useful when you want to inspect raw markup after the crawl, but increases database size significantly.
`--export-csv`	path	—	Export crawl results to a CSV file at this path after the crawl completes. The CSV contains one row per page with the same columns as the desktop app's "Export all" function.
`--export-sitemap`	path	—	Generate an XML sitemap from crawl results and write it to this path. Useful for producing a sitemap from what the crawler actually found, rather than what the site claims to have.
`--format`	string	`text`	Output format: `text`, `json`, or `junit`. See Output formats below.
`-o`, `--output`	path	stdout	Write the report to a file instead of stdout.
`--fail-on`	string	`none`	Severity threshold that causes exit code 1: `none`, `critical`, `warning`, or `notice`. See Exit codes.
`--db`	path	in-memory	Write the crawl to a SQLite database at this path. Without it, results live in memory and are discarded after the report is written.
`-q`, `--quiet`	flag	`false`	Suppress progress output on stderr, keeping stdout clean for piping.

Output formats

Text

The default. A human-readable summary grouped by check, suitable for reading in a terminal:

Crawl of https://example.com
  412 crawled, 3 failed, 12s elapsed
Response codes
  [critical] Client error (4xx)    3

JSON

A machine-readable object with crawl statistics and per-check issue counts, suitable for scripting and dashboards:

{
  "url": "https://example.com",
  "crawl": {
    "urlsCrawled": 412,
    "urlsFailed": 3,
    "elapsedSeconds": 12
  },
  "issues": [
    {
      "key": "status_4xx",
      "group": "Response codes",
      "label": "Client error (4xx)",
      "severity": "critical",
      "count": 3
    }
  ]
}

JUnit XML

One <testcase> per check. Most CI systems consume JUnit natively, giving you a test report tab with no extra tooling.

How each check maps to JUnit depends on the --fail-on threshold:

Checks with findings at or above the threshold produce a <failure> element — these are the issues that cause exit code 1.
Checks with findings below the threshold produce a <skipped> element — present in the report but not treated as failures.
Clean checks are empty <testcase/> elements.

This means the CI report and the exit code always agree: anything the exit code treats as a failure is marked as one in the JUnit output.

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 crawled at all. This is distinct from "issues found" because it means no audit ran.

By default --fail-on is none, so the CLI always exits 0 on a successful crawl regardless of findings. Set it 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

Severity ordering is cumulative: --fail-on warning also fails on criticals, and --fail-on notice fails on everything. The threshold sets a floor, not a single level.

Empty crawl handling

If nothing was crawled — the start URL is unreachable, DNS fails, or the server returns nothing — the exit code is 2, not 0. A crawl that fetched zero pages has no findings, but that is not a clean bill of health; it means no inspection happened.

In JUnit mode an empty crawl renders a single failing <testcase> so the CI report shows an explicit failure rather than an empty, passing suite. Without this, a misconfigured URL would produce a green build — the most dangerous kind of false positive.