Reference

Usage

The same rule set runs from the command line or from TypeScript. Both take a document and return the same result object.

Install

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

install

# one-line install (installs the `officelens` binary)$ curl -fsSL https://raw.githubusercontent.com/srivtx/officelens/main/install.sh | sh# or run once, without installing$ bunx github:srivtx/officelens#main report.docx# add to a project as a dev dependency$ bun add -d github:srivtx/officelens# install globally$ bun add -g github:srivtx/officelens$ officelens report.docx

Command-line flags

Every flag officelens accepts.
Flag	Description
`officelens <files…>`	Audit one or more `.docx` or `.pptx` files.
`--dir <path>`	Audit every `.docx`/`.pptx` file in a directory (non-recursive, sorted).
`--json`	Print a machine-readable JSON report to stdout: one object for a single file, an array for more than one.
`--quiet`, `-q`	Print only a one-line summary for each file.
`--sarif <file>`	Write a SARIF 2.1.0 log for GitHub code scanning.
`--fail-on <level>`	`error` (default), `warning`, `info`, or `none` — sets the exit-code threshold.
`--`	Stop option parsing; every following argument is treated as a file path.
`--version`, `-v`	Print the version and exit.
`--help`, `-h`	Show usage.

Examples

examples

# audit files$ officelens report.docx deck.pptx# audit a directory of documents$ officelens --dir docs/# machine-readable output$ officelens report.docx --json# one summary line per file$ officelens report.docx --quiet# SARIF for GitHub code scanning$ officelens report.docx --sarif officelens.sarif# fail CI on warnings too$ officelens report.docx --fail-on warning

Help output

The full usage text, verbatim from officelens --help:

officelens - offline accessibility auditor for DOCX and PPTX

Usage:
  officelens <file...> [options]
  officelens --dir <path> [options]

Options:
  --dir <path>         Audit every .docx/.pptx file in <path> (non-recursive, sorted)
  --json               Print machine-readable JSON; one object for a single file,
                       a JSON array when auditing more than one
  --quiet, -q          Print only a one-line summary for each file
  --sarif <path>       Write a SARIF 2.1.0 report to <path>
  --fail-on <level>    Exit 1 on: error (default), warning, info, none
  --version, -v        Print the version and exit
  -h, --help           Show this message

Value flags accept either "--flag value" or "--flag=value". Use "--" to stop
option parsing; every following argument is treated as a file path.

Exit codes:
  0  no findings at or above --fail-on
  1  findings at or above --fail-on
  2  invalid usage, or a package that cannot be parsed as OOXML
  3  an input file or directory could not be read, or the report could not be written

Exit codes

The exit code is the CI gate.
Code	Meaning
`0`	No findings at or above `--fail-on`.
`1`	Findings at or above `--fail-on`.
`2`	Invalid usage, or a package that cannot be parsed as OOXML.
`3`	An input file or directory could not be read, or the 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.

{
  "file": "fixtures/bad.docx",
  "kind": "docx",
  "counts": { "error": 2, "warning": 2, "info": 0 },
  "issues": [
    {
      "code": "DOCX-ALT-001",
      "severity": "error",
      "wcag": "1.1.1",
      "location": "word/document.xml",
      "message": "Drawing (docPr id=1) has no alt text (descr or title)."
    }
  ]
}

Library

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

import { audit, toSarif } from "officelens";

const result = audit(bytes, "report.docx");
// { file, kind: "docx", issues, counts: { error, warning, info } }

const sarif = toSarif(result, "officelens", "0.2.0");

← Rules CI →