Reference

Usage

The same rule set runs from the command line or from TypeScript. audit reports, fix writes a repaired EPUB, and both return the same result object.

Install

booklens is not published to npm. Install it with the one-line script, or run it without installing.

install

# One-line install (installs the `booklens` binary)$ curl -fsSL https://raw.githubusercontent.com/srivtx/booklens/main/install.sh | sh# Or run once, without installing$ bunx github:srivtx/booklens#main audit book.epub# Install globally$ bun add -g github:srivtx/booklens$ booklens audit book.epub# Add to a project as a dev dependency$ bun add -d github:srivtx/booklens

Commands and flags

Command-line options.
Flag	Description
`booklens audit <file>`	Report accessibility issues in an EPUB.
`booklens fix <file>`	Write a repaired EPUB (default `<input>.fixed.epub`).
`-o <path>`	`fix`: output path.
`--dir <path>`	Read every `.epub` in `<path>` (non-recursive, sorted).
`--json`	`audit`: print the full result as JSON.
`--quiet`, `-q`	Print a single summary line per file.
`--sarif <path>`	Write a SARIF 2.1.0 report to `<path>`.
`--fail-on <level>`	Exit `1` at or above this severity: `error` (default), `warning`, `info`, or `none`.
`--language <lang>`	`fix`: language to write when one is missing (default `en`).
`--title <title>`	`fix`: title to write when one is missing.
`--only <codes>`	`fix`: comma-separated rule codes to apply (for example `E001,E002,W010`).
`--dry-run`	`fix`: report changes without writing a file.

Full help

booklens --help

booklens 0.2.0Usage:  booklens audit <file> [options]  booklens audit --dir <path> [options]  booklens fix <file> [options]  booklens fix --dir <path> [options]Commands:  audit               Report accessibility issues in an EPUB.  fix                 Write a repaired EPUB (default: <input>.fixed.epub).Options:  -o <path>           fix: output path (single input only)  --dir <path>        Read every .epub in <path> (non-recursive, sorted)  --json              Print machine-readable JSON; one object for a single                      input, an array when reading more than one  --quiet, -q         Print a single summary line per file  --sarif <path>      Write a SARIF 2.1.0 report to <path>  --fail-on <level>   Exit 1 at or above this severity: error (default),                      warning, info, or none  --language <lang>   fix: language to write when one is missing (default: en)  --title <title>     fix: title to write when one is missing  --only <codes>      fix: comma-separated rule codes to apply                      (e.g. --only E001,E002,W010)  --dry-run           fix: report changes without writing a file  -v, --version       Print the version and exit  -h, --help          Print this help and exitEvery value flag also accepts --flag=value. A lone -- ends option parsing.Unknown options are rejected.Exit codes:  0  success; no findings at or above --fail-on  1  findings at or above --fail-on  2  invalid usage, or a file that cannot be parsed as an EPUB  3  an input file/directory or output report could not be read/writtenExamples:  booklens audit book.epub  booklens audit book.epub --json --sarif booklens.sarif  booklens audit --dir public --quiet --fail-on warning  booklens fix book.epub -o book.fixed.epub --language en --title "My Book"  booklens fix book.epub --only E001,E002 --dry-run

Examples

examples

# Audit: human output, exit 1 at or above the threshold$ booklens audit book.epub# Audit: machine-readable for CI$ booklens audit book.epub --json# Fix: write a repaired EPUB$ booklens fix book.epub -o book.fixed.epub --language en --title "My Book"# Preview the fixes without writing anything$ booklens fix book.epub --dry-run# Apply only selected fixes$ booklens fix book.epub --only E001,E002,W010# Emit SARIF for GitHub code scanning$ booklens audit book.epub --sarif booklens.sarif

Exit codes

The exit code is the CI gate.
Code	Meaning
`0`	Success; no findings at or above `--fail-on`.
`1`	Findings at or above `--fail-on`, or invalid arguments.
`2`	The input could not be read or is not a valid EPUB.
`3`	An input file/directory or output report could not be read/written.

--fail-on affects only the exit code. Every issue is still reported and included in SARIF output.

JSON output

With --json, each issue is an object like this one, with code, severity, message, location, fixable, and wcag. A single input produces one object; more than one produces an array.

{
  "file": "fixtures/inaccessible.epub",
  "issues": [
    {
      "code": "E008",
      "severity": "error",
      "message": "1 image(s) missing an alt attribute.",
      "location": "OEBPS/chapter1.xhtml",
      "fixable": true,
      "wcag": "1.1.1"
    }
  ]
}

Library

The same rules power the CLI and the library. Import them directly when you are already in TypeScript.

import { audit, fixEpub } from "booklens";

const report = audit(bytes, "book.epub");

if (report.counts.error > 0) {
  const { data, applied, remaining } = fixEpub(bytes, {
    language: "en",
    title: "My Book",
  });
  // data: repaired EPUB bytes, applied: changelog, remaining: re-audit issues
}

← Rules CI →