@mrbilit/mrz-cli

Command-line tool that runs the full MRZ scanner pipeline over document images and writes the parsed fields as JSON. Installed as the mrz2json binary.

This package is part of mrbilit/mrz-scanner, a fork of alsenet-labs/mrz-scanner.

Installation

Install globally from npm:

npm install -g @mrbilit/mrz-cli

This installs the mrz2json command:

mrz2json --help

Build from source

From the repository root:

yarn install
yarn workspace @mrbilit/mrz-cli build

Run directly from the repository:

node packages/mrz-cli/dist/cli.js passport.jpg

Or link the local package globally:

cd packages/mrz-cli
npm link

The mrz2json command will then be available on $PATH.

Usage

mrz2json [options] <file...>

Options:
  -d, --dest-dir <path>   Output directory for JSON files (must exist, must be under cwd)
  -f, --format <type>     Output format: json (default) or text
  -c, --confidence        Include per-character confidence scores in the JSON
  -h, --help              Show help
  -v, --version           Show version

Examples

Write passport.jpg.mrz.json next to each input:

mrz2json a.jpg b.png c.jpeg

Collect every JSON file into out/:

mkdir -p out && mrz2json -d out *.jpg

Print the raw MRZ lines to stdout without writing a file:

mrz2json -f text passport.jpg

Include per-character confidence scores in the JSON:

mrz2json -c passport.jpg

Output

Output JSON contains the parsed fields flat at the top level (whatever the mrz package produces), plus:

• _fixed: true when OCR-confusion corrections were applied.
• _confidence: number[][] when -c was passed.

Security

• Input files above 50 MB are rejected before decoding.
• --dest-dir is resolved and forced to stay under the working directory; absolute paths that escape cwd are rejected, as are path-traversal components.
• Output JSON files are written with mode 0600 (owner read/write only).
• On parse failure, raw OCR text is not echoed to stderr because it can contain partial PII.

Exit codes

• 0 — all files processed successfully.
• 1 — one or more files failed. The CLI still attempts every remaining file and reports each failure on stderr.

License

This project is distributed under the GNU Affero General Public License, version 3 or later (AGPL-3.0-or-later).

The original project and source code are Copyright © 2018-2025 ALSENET SA.

See LICENSE for the full license text.