ExaDev/document-cli

document-cli

This repository has moved. document-cli now lives at packages/document-cli in the ExaDev/documents.js monorepo. This repository is archived and will receive no further commits, releases, issues, or pull requests — file issues and send pull requests against the monorepo instead. The npm package itself is unaffected: document-cli keeps publishing from its new home under the same name.

A command-line interface and an interactive terminal (Ink) app for documents.js: every docx/pptx/odt/odp/ods/odg/odf/pdf/odm/odb/xlsx/csv/svg/markdown conversion, bridge, and editor documents.js exposes, plus the outline projection document-outline.js builds over any readable document, wired up as a scriptable subcommand or a full-screen terminal editor. Installs as either document-cli or doculi.

document-cli adds no conversion or editing logic of its own — it is a dispatch layer over documents.js's existing conversion functions, DocumentConverter port, live-view editors, and .odb/PDF readers. What it adds is two ways to drive them without writing TypeScript: a scriptable, Unix-shaped CLI (stdin/stdout, exit codes, --json diagnostics) for pipelines, and a full-screen Ink terminal app for browsing and editing a document interactively.

graph TD
    schema("document-schema.js")
    ooxml("ooxml.js")
    odf("odf.js")
    pdfcodec("pdf-codec")
    mdcodec("markdown-codec")
    bytecodec("byte-codec")
    documents("documents.js")
    outline("document-outline.js")
    mcp("document-mcp")
    cli("document-cli")

schema -- odf schema -- pdfcodec schema -- mdcodec schema -- documents schema -- outline ooxml -- documents odf -- documents pdfcodec -- documents mdcodec -- documents bytecodec -- pdfcodec bytecodec -- documents documents -- mcp pdfcodec -- mcp documents -- cli outline -- cli odf -- cli pdfcodec -- cli

click schema "https://github.com/ExaDev/document-schema.js" "document-schema.js" click ooxml "https://github.com/ExaDev/ooxml.js" "ooxml.js" click odf "https://github.com/ExaDev/odf.js" "odf.js" click pdfcodec "https://github.com/ExaDev/pdf-codec" "pdf-codec" click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec" click bytecodec "https://github.com/ExaDev/byte-codec" "byte-codec" click documents "https://github.com/ExaDev/documents.js" "documents.js" click outline "https://github.com/ExaDev/document-outline.js" "document-outline.js" click mcp "https://github.com/ExaDev/document-mcp" "document-mcp" click cli "https://github.com/ExaDev/document-cli" "document-cli"

style cli fill:#f9a825,stroke:#333,stroke-width:3px

## Why

`documents.js` is a library, not a tool — everything it does happens through function calls from TypeScript/JavaScript. Most people who want to convert a docx to a PDF, extract an `.odb` table to CSV, or poke at a PDF's structure from a terminal don't want to write a script to do it. `document-cli` is that missing entry point: every one of documents.js's direct conversion pairs, its generic converter, its `.odm`/`.odb` extraction functions (including a bounded SQL engine over an `.odb`'s own tables and full report rendering), its PDF inspector, and its document metadata/source-font introspection become a single command-line invocation, and its seven live-view editors (docx/pptx/odt/odp/ods/odg/markdown) become a keyboard-driven terminal app that never needs a code editor open at all.

[`document-mcp`](https://github.com/ExaDev/document-mcp) is the sibling frontend over the identical `documents.js` library — an MCP server rather than a terminal CLI/TUI — so the two are independent consumers of one shared implementation, each exposing whatever subset of it suits a human at a terminal versus an MCP-speaking agent.

The CLI and the TUI are deliberately not two separate implementations of the same logic. The TUI's own document-opening, saving, and PDF-export code (`src/tui/format/`) calls the identical `documents.js` functions the CLI commands call — `openDocx`/`createDocx`/`docxToPdf` and their five siblings per format, plus `readOdbTables`/`readPdf` for the two read-only sources — so there is exactly one place either surface can drift from what documents.js itself does: nowhere. This CLI adds no conversion logic of its own, so a conversion's fidelity — which pairs round-trip losslessly, which are a best-effort reconstruction, and why — is exactly what [`documents.js`'s own Fidelity section](https://github.com/ExaDev/documents.js#fidelity) documents, table included; it is not restated here.

## Getting started

Requires Node.js `>=20`.

npm i -g document-cli
# or, identically:
npm i -g doculi

Both names install the exact same package and the exact same binary — package.json's bin field declares both document-cli and doculi pointing at the one built entry point unconditionally, so there is no "real" name and an alias; pick whichever you find easier to type. This mirrors the alias-publishing pattern already established elsewhere in this package family (documents.js's own scoped @exadev/documents.js republish to GitHub Packages) — a second name for the same build, not a second build.

Usage

Every conversion and extraction command reads one input and writes one output. Pass - for either to use stdin/stdout instead of a file — useful for piping through other tools without a temp file:

document-cli docx-to-pdf report.docx report.pdf
cat report.docx | document-cli docx-to-pdf - - > report.pdf

Commands

The explicit <source-to-<target conversions — one command per pair createLocalDocumentConverter().conversions declares in documents.js (confirmed by running the built CLI's own formats command, not assumed): every ordered pair of the ten content formats — docx, pptx, xlsx, odt, odp, ods, odg, svg, csv, markdown — in both directions as a PDF-bypassing bridge (a pair whose formats share one ContentDocument variant, like odt-to-docx or ods-to-xlsx, copies content across directly; a cross-variant pair, like docx-to-pptx, xlsx-to-markdown, or odg-to-svg, swaps the document's content variant through a semantic transform); each of those ten plus odf into pdf (docx-to-pdf, xlsx-to-pdf, csv-to-pdf, svg-to-pdf, odf-to-pdf, ...); and pdf back into the same ten (pdf-to-docx, pdf-to-xlsx, pdf-to-csv, pdf-to-svg, ... — there is no pdf-to-odf; odf-to-pdf is one-way, see documents.js's own README). Each takes <input [output]:

document-cli docx-to-pdf report.docx report.pdf
document-cli ods-to-xlsx budget.ods budget.xlsx

convert <input [output] — the same conversions through one generic command, inferring source format from the input's extension and target format from the output's extension (or --to <format when the output path doesn't carry one, e.g. writing to stdout):