transcribe-cli

Agent-first local document parser: one file in, one JSON receipt out.

Point it at a local document — PDF, HWP, HWPX, HWPML, DOCX, XLS, XLSX, or CSV/TSV — and it detects the format, routes to the right engine internally, writes a markdown rendering and a structured JSON rendering to a per-run output directory, and prints a small JSON receipt on stdout pointing at those artifacts. Document content never goes to stdout, so an agent's context stays clean. There is no engine choice, no OCR toggle, no output-mode flag.

• PDFs run through opendataloader-pdf, fully local; hybrid mode (scanned-page OCR, complex tables, LaTeX formulas, figure descriptions) is on by default, with the backend auto-started and kept warm.
• Korean office and HWP documents (HWP/HWPX/HWPML) plus Word/Excel (DOCX/XLS/XLSX) parse natively through kordoc — no export-to-PDF step.
• CSV/TSV converts deterministically to a markdown table.

Local files only. This tool does not fetch URLs.

Install

From the transcribe-cli repo root:

npm install
scripts/install.sh                 # build + link the CLI and skill (native mode ready)
scripts/install.sh --with-hybrid   # also provision the Python hybrid backend (heavy)

scripts/install.sh creates:

• ~/.local/bin/transcribe-cli
• a transcribe-cli skill link in every detected harness (OpenCode, Codex, Cursor), all pointing at the single source of truth skill/SKILL.md.

Requirements: Node 20.19+. The PDF path needs Java 11+ (bundled engine is a JAR); hybrid mode adds Python 3.12 + uv. The kordoc formats and CSV need nothing beyond Node.

Usage

transcribe-cli /path/to/paper.pdf
transcribe-cli /path/to/report.hwp
transcribe-cli /path/to/sheet.xlsx
transcribe-cli '{"input":"/path/to/file.docx"}'   # JSON request on argv
printf '%s' '{"input":"/path/to/paper.pdf"}' | transcribe-cli

What comes back on stdout — a receipt, never content:

{
  "success": true,
  "format": "hwp",
  "engine": "kordoc",
  "status": "ok",
  "input": "/path/to/report.hwp",
  "outputDir": "/tmp/transcribe-cli-report-Ab12Cd",
  "artifacts": {
    "markdown": "/tmp/transcribe-cli-report-Ab12Cd/report.md",
    "json": "/tmp/transcribe-cli-report-Ab12Cd/report.json",
    "images": "/tmp/transcribe-cli-report-Ab12Cd/report.imgs"
  },
  "metadata": { "title": "...", "pageCount": 3 },
  "warnings": [],
  "elapsedMs": 94
}

On failure the exit code is nonzero and stdout carries { "success": false, "error": { "code", "message" } } with a stable, branchable code — one class per code: UNSUPPORTED_FORMAT, FILE_NOT_FOUND, PARSE_FAILED, ENCRYPTED_DOCUMENT, INVALID_INPUT, URL_INPUT, EMPTY_INPUT, JAVA_MISSING, and the PDF hybrid-backend codes BACKEND_NOT_INSTALLED / BACKEND_START_FAILED / BACKEND_START_TIMEOUT / BACKEND_UNREACHABLE. The full reference (with meanings) lives in skill/SKILL.md. On failure, stderr carries the human-readable error line.

Supported formats

Input	Engine	Notes
PDF	opendataloader-pdf	Text, tables, headings, reading order; + OCR / LaTeX formulas / figure descriptions in hybrid mode
HWP / HWPX / HWPML	kordoc	Hancom office documents, parsed natively (HWP 3.x/5.x, OOXML-era HWPX, HWPML)
DOCX / XLS / XLSX	kordoc	Word and Excel, parsed natively
CSV / TSV	built-in parser	One markdown table per file; RFC 4180 quoting; ragged rows padded

PowerPoint and legacy .doc are rejected with a one-line conversion hint.

More detail

• Agent-facing contract and receipt/error reference: skill/SKILL.md
• Setup, architecture, troubleshooting, and maintenance notes: AGENTS.md

License & attribution

MIT. See LICENSE.

transcribe-cli is a router/normalizer over engines written by others:

• opendataloader-pdf (Apache-2.0) — the PDF engine (bundled JAR via @opendataloader/pdf), plus its optional hybrid backend built on docling and EasyOCR.
• kordoc (MIT) — the HWP/HWPX/HWPML/DOCX/XLS/XLSX engine.

All parsing credit belongs to those projects.