Reference
Usage
The same rule set runs from the command line or from TypeScript. Both take a source string and return the same result object.
Install
# one-line install (installs the `iconlens` binary)$ curl -fsSL https://raw.githubusercontent.com/srivtx/iconlens/main/install.sh | sh# run once, without installing$ bunx github:srivtx/iconlens#main icons/*.svg# add as a project dev dependency$ bun add -d github:srivtx/iconlens
Command-line flags
| Flag | Description |
|---|---|
iconlens <files…> | Audit one or more .svg files. Use - to read standard input. |
--dir <path> | Audit every .svg file directly under a directory (sorted, non-recursive). |
--json | Print a machine-readable JSON report to stdout: one object, or an array for multiple inputs. |
--quiet, -q | One summary line per file. |
--sarif <file> | Write a SARIF 2.1.0 log for GitHub code scanning. |
--fail-on <level> | error (default), warning, info, or none — the exit-code threshold. |
-- | End option parsing; treat the rest as file names. |
-h, --help / -v, --version | Print help or the version and exit. |
Examples
# audit files$ iconlens icons/*.svg# audit a directory$ iconlens --dir icons/# machine-readable output$ iconlens logo.svg --json# SARIF for GitHub code scanning$ iconlens logo.svg --sarif iconlens.sarif# fail CI on warnings too$ iconlens logo.svg --fail-on warning
Exit codes
| Code | Meaning |
|---|---|
0 | No issue at or above --fail-on. |
1 | At least one issue at or above --fail-on. |
2 | Invalid usage, input over the 16 MiB limit, or input that is not well-formed SVG. |
3 | I/O error: an input could not be read, or a report could not be written. |
--fail-on affects only the exit code. Every issue is still reported and included in SARIF output.
JSON output
With --json, a single input produces one object; more than one produces an array. Field order is stable, so a diff means a real change.
{
"file": "logo.svg",
"counts": { "error": 3, "warning": 2, "info": 0 },
"issues": [
{
"code": "SVG-NAME-001",
"severity": "error",
"wcag": "4.1.2",
"location": "logo.svg",
"message": "Root svg has role=\"img\" but no accessible name; add aria-labelledby, aria-label, or a first-child <title>."
}
]
}Library
The same rules power the CLI and the library. Import them directly when you are already in TypeScript.
import { auditSvg, accessibleName, parseSvg, toSarif } from "iconlens";
const result = auditSvg(source, "logo.svg");
const name = accessibleName(parseSvg(source));
// { name: "Company logo", source: "aria-labelledby" }
const sarif = toSarif(result, "iconlens", "0.2.0");