Command-Line Interface¶

scanlib installs a scanlib command for scanning from the shell. It can also be invoked as python3 -m scanlib.

Listing Scanners¶

scanlib list

Prints a table of all available scanners with index, name, ID, location, and backend. The index can be used with -s in other commands.

Viewing Capabilities¶

scanlib info -s 0

Opens the scanner and displays its capabilities: supported sources, resolutions, color modes, maximum scan area, and defaults. The -s flag accepts a numeric index, a scanner ID, or a substring of the scanner name.

Scanning¶

scanlib scan -o document.pdf

Scans a document and writes a PDF. All scan options can be configured via flags:

scanlib scan -o scan.pdf \
    --dpi 600 \
    --color-mode gray \
    --source flatbed \
    --format jpeg \
    --jpeg-quality 90

Options¶

-s, --scanner: Scanner index, ID, or name substring. Default: 0 (first scanner).
-o, --output: Output PDF file path. Default: scan.pdf.
--dpi: Scan resolution in DPI. Default: scanner default.
--color-mode: Color mode: color, gray, or bw. Default: scanner default.
--source: Scan source: flatbed or feeder. Default: scanner default.
--scan-area: Scan region as x,y,width,height in 1/10 millimeters. Example: --scan-area 0,0,2100,2970 for full A4.
--format: Image format inside the PDF: jpeg or png. Default: auto (PNG for BW, JPEG otherwise).
--jpeg-quality: JPEG quality from 1 to 100. Default: 85.
--pages: Number of flatbed pages to scan, or ask for interactive prompting between pages. Ignored when source is feeder.
--bw-threshold: BW mode threshold from 0 to 255. Pixels with a grayscale value ≥ this become white, below become black. Default: 128. Lower values produce lighter output, higher values darker.

Multi-Page Scanning¶

Scan a fixed number of flatbed pages:

scanlib scan -o multipage.pdf --pages 3

Prompt between pages interactively:

scanlib scan -o multipage.pdf --pages ask

When using a document feeder, all pages are scanned automatically:

scanlib scan -o feeder.pdf --source feeder

Progress and Output¶

Progress is reported on stderr so it does not interfere with stdout. A summary is printed when the scan completes:

Scanning with HP Officejet @ 300 DPI, color...
Scanning... 100%
Saved 1 page(s) to scan.pdf (54321 bytes, 2480x3508 px)

Resetting an eSCL Scanner¶

If an eSCL scanner gets stuck (e.g. due to a stale scan job), you can cancel active jobs:

scanlib reset -s escl:192.168.1.5:443

This checks the scanner status, finds any active jobs, and cancels them. Only supported for eSCL scanners.