Reference

Usage

The same rule set runs from the command line or from TypeScript. Both take an ODF package and return the same result object.

Install

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

install

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

Command-line flags

Every flag odflens accepts.
Flag	Description
`odflens <files…>`	Audit one or more `.odt`, `.ods`, or `.odp` files.
`--dir <path>`	Audit every `.odt`/`.ods`/`.odp` file in `<path>` (non-recursive, sorted).
`--json`	Print a single JSON array of results to stdout.
`-q`, `--quiet`	Print a single summary line per file.
`--sarif <path>`	Write a SARIF 2.1.0 report to `<path>`.
`--fail-on <level>`	`error` (default), `warning`, `info`, or `none` — the exit-code threshold.
`-v`, `--version`	Print the odflens version.
`-h`, `--help`	Show help.
`--`	Treat every following argument as an input file.

Options that take a value also accept the --option=<value> form. A --dir with no matching .odt/.ods/.odp files is an error (exit 2).

Examples

examples

# audit one or more files$ odflens report.odt sheet.ods deck.odp# a whole directory$ odflens --dir docs/# machine-readable output$ odflens report.odt --json# one summary line per file$ odflens report.odt --quiet# SARIF for GitHub code scanning$ odflens report.odt --sarif odflens.sarif# choose when the exit code becomes non-zero$ odflens report.odt --fail-on warning

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, an empty `--dir`, or a document that cannot be read or parsed as ODF.
`3`	An input file or an output report could not be read or written.

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

JSON output

With --json, odflens prints a single array of results. Field order is stable, so a diff means a real change.

[
  {
    "file": "bad.ods",
    "kind": "ods",
    "counts": { "error": 2, "warning": 0, "info": 0 },
    "issues": [
      {
        "code": "ODF-LANG-001",
        "severity": "error",
        "wcag": "3.1.1",
        "location": "bad.ods",
        "message": "Document does not declare a language (dc:language or xml:lang / fo:language)."
      },
      {
        "code": "ODF-TITLE-002",
        "severity": "error",
        "wcag": null,
        "location": "bad.ods",
        "message": "Document metadata has no non-empty dc:title."
      }
    ]
  }
]

Library

The same rules power the CLI and the library. Call audit(bytes, name) directly from TypeScript.

import { audit, toSarif } from "odflens";

const result = audit(bytes, "report.odt");
// { file, kind: "odt", issues, counts, fatal? }

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

← Rules CI →