Docs / Getting started

Getting started

Three ways to drive the same conversion: type a command, drag files onto the desktop app, or leave a service running that watches a folder. Add MCP for agents and that's four entry points.

Your first conversion#

Put files in raw/ and run it with no arguments — it lists what's there and lets you pick by number:

$ morsel
# or pass a path directly, or drag a file or folder into the terminal
$ morsel report.pdf
$ morsel ~/Documents/contracts/

Results go to output/<filename>/ — one folder per file, so same-named documents don't overwrite each other and extracted images have somewhere to live. Markdown and JSON are the default outputs.

Input and output#

Five output formats: markdown, json, html, text, and pdf — that last one is an annotated PDF that draws a coloured box around every block it recognised, so you can check the parse against the original.

$ morsel report.pdf -f markdown,json,text
$ morsel report.pdf --pages 1,3,5-7     # selected pages only
$ morsel locked.pdf -p PASSWORD

Common options#

--better-tables

Enhanced table detection. The default finds tables by their borders; borderless ones need this

--images

off / embedded / external (default). External reliably writes image files

--page-markers

Insert page markers into Markdown and text so you can cite back to the page

--sanitize

Replace emails, phone numbers, ID numbers, card numbers and IPs with placeholders

--header-footer

Keep running heads and footers (dropped by default)

--keep-all-content

Turn off content filtering — recovers off-page and very small text when you suspect something is missing

Put the combinations you use often into config.toml at the project root. The rule is simple: config only changes defaults; an explicit command-line flag always wins. A key you got wrong is reported and ignored rather than fatal.

Batches and long runs#

$ morsel ~/contracts/ --jobs 4         # four worker processes
$ morsel ~/contracts/ --force          # re-convert everything
$ morsel --watch ~/Dropbox/inbox       # watch a folder

• Resume is on by default. Successful runs are recorded with the source file's modification time, size and a signature of the options used. Change the file, the output format or an option and it re-converts. The record is written after each file, so a power cut costs you nothing already done.
• Failures aren't recorded, so they're retried on the next run.
• Every batch writes a report.csv: status, pages, output count, duration, whether OCR ran, and the reason for any failure. UTF-8 with BOM, so Excel opens it without mangling non-ASCII text.
• Watch mode waits for files to settle — two consecutive scans with the same size and timestamp — so it never converts a half-copied file. This matters on synced folders.

AI-facing output#

$ morsel report.pdf --rag-chunks --chunk-size 400
$ morsel report.pdf --export-tables
$ morsel ~/research/ --merge
$ morsel report.pdf --qa

RAG chunks

Split by heading level within a token budget, written one chunk per line to .chunks.jsonl, each carrying its page range and heading path. Headings start new chunks, sections too small to stand alone merge forward, and long body text is split by line then by sentence

Table CSV

One CSV per table, page number in the filename; merged cells are written to their top-left anchor

Merge

Combines the batch's Markdown into a single merged.md with a clickable table of contents, one top-level heading per document

Quality check

Produces an annotated PDF (headings blue, body green) plus a per-page CSV flagging blank pages, scanned-looking pages and thin ones, and reports "N of M pages worth reviewing" in the log

Chunking and table export both read the JSON structure tree. If you didn't ask for JSON output, it's generated anyway.

Scans and OCR#

OCR defaults to auto: each file's text density is probed first, and only files that look scanned go through OCR — it's much slower than a normal conversion, and auto means you only pay that cost when you have to. Use --ocr off to disable it entirely, or --ocr force to run it on everything.

When the OCR service isn't running you don't get a wall of connection errors — you get a clear message about how to start it, and the file is converted in normal mode instead. Installation is on the download page.

Desktop app and web service#

• Desktop app: drag files in, tick the options, convert. The work runs on a background thread so the window stays responsive, progress is live, and one failed file doesn't stop the rest.
• Web service: a watched folder plus a local web page, meant to be left running. Upload from the browser, watch the log, download results. It binds to localhost and has no access control — don't put it on an untrusted network.