HSC CLI Module

The Command Line Interface (CLI) module of HTML Sanity Check (HSC) enables to check generated or native HTML documentation from the command line.

Installation (Command Line Interface)

Prerequisites

The HSC CLI needs Java 8 (java executable) or higher on the respective OS search path (${PATH} on Linux/macOS, %path% on Windows).

SDKMAN

If you use SDKMAN, you can install HSC as SDKMAN candidate: sdk install hsc.

Download

Alternatively,

  • Download the HSC CLI from the release page.

  • Unpack the file in a convenient place, e.g., /usr/local/hsc.

Usage

Execute the CLI tool with the following command. If the sourceDirectory is omitted, HSC uses the current directory as base-directory to search for HTML files.

Linux / macOS
hsc [ options ] [ sourceDirectory ]
Windows
hsc.bat [ options ] [ sourceDirectory ]

Options

The CLI tool exposes a few options as part of its configuration:

<sourceDirectory> (optional)

HSC searches this directory for HTML files.

Type: Directory

Default: Current directory (.)
--sourceDocuments <…​> (optional)

An override to process several source files, which must be a subset of all files available in sourceDir.

Type: List of files

Default: All files in sourceDir whose names end with .html
--checkingResultsDir <…​> (optional)

Directory where HSC writes the checking results.

Type: Directory

Default: ./reports/htmlSanityCheck/
--junitResultsDir <…​> (optional)

Directory where HSC writes the results in JUnit XML format. Many tools can read JUnit XML, including CI environments.

Type: Directory

Default: ./test-results/htmlchecks/
--failOnErrors (optional)

Fail the build if HSC detected any error in the checked pages.

Type: Boolean

Default: false
--httpConnectionTimeout <value> (optional)

Timeout for HTTP requests in milliseconds.

Type: Integer

Default: 5000
--ignoreLocalHost (optional)

Ignore localhost as hostname.

Type: Boolean

Default: false
--ignoreIPAddresses (optional)

Ignore IP addresses as hostname.

Type: Boolean

Default: false
--checkerClasses <…​> (optional)

The set of checker classes to be executed.

Type: List

Default:

Checker Classes
// Keep the list ordering to ensure
// report ordering comparability
// with HSC 1.x versions
MissingAltInImageTagsChecker.class,
MissingImageFilesChecker.class,
DuplicateIdChecker.class,
BrokenHttpLinksChecker.class,
ImageMapChecker.class,
BrokenCrossReferencesChecker.class,
MissingLocalResourcesChecker.class
--excludes (optional)

This is a set of regular expressions of URLs or even hosts that HSC should not check.

Type: Set.

Default: Empty list

[]
--httpWarningCodes (optional)

HTTP response codes treated as warning.

Type: List

Default:

100, 101, 102
// Redirects included
301, 302, 303, 307, 308
HTTP Redirects

Note that HSC treats HTTP redirects as a warning to make the user aware of the correct or new location (cf. Issue 244). Some HSC reports contain the respective location.
--httpErrorCodes (optional)

HTTP response codes treated as error.

Type: List

Default:

400, 401, 402, 403, 404,
405, 406, 407, 408, 409,
410, 411, 412, 413, 414,
415, 416, 417, 418, 421,
422, 423, 424, 425, 426,
428, 429, 431, 451,
500, 501, 502, 503, 504,
505, 506, 507, 508, 510,
511
--httpSuccessCodes (optional)

HTTP response codes that HSC treats as success.

Type: List

Default:

200, 201, 202, 203, 204,
205, 206, 207, 208, 226
HTTP response code handling

The lists shown above are the default HTTP response codes handled by HSC. The mentioned configurations effectively move the configured codes around, i.e., if you add 308 to httpErrorCodes it is automatically removed from its default list (httpWarningCodes).

Examples

Basic Example

java -jar htmlSanityCheck-cli-<version>.jar --sourceDir ./docs

Extended Example

java -jar htmlSanityCheck-cli-<version>.jar \
  --sourceDir ./docs \
  --checkingResultsDir ./report/htmlchecks \
  --failOnErrors true \
  --httpConnectionTimeout 1000 \
  --checkerClasses DuplicateIdChecker,MissingImageFilesChecker

Compatibility

We test the HSC CLI tool with the following Java versions:

  • Java 8

  • Java 11

  • Java 17

  • Java 21

Development Versions

In case you want to use a current development (or arbitrary branch or tag) version from GitHub, you can build the CLI tool from source.

Clone the repository
git clone https://github.com/aim42/htmlSanityCheck.git
cd htmlSanityCheck
Build the CLI tool
./gradlew integrationTest

Gradle generates the application to htmlSanityCheck-cli/build/install/hsc/.