Skip to main content
MonoDoc is the local-file ingestion edge of the Monomento stack. It invokes a markitdown companion process, emits Markdown, and can index the result in Monomento as doc_type=file. Published contract: monodoc 0.1.1, OpenCLIs build 2026-04-27-191303. The installed-state row, immutable payload, public CDN pointer, and CDN release metadata agree on this identity. The exact installed payload was also code-signature verified on macOS.

​
Quick Start

Always run which on a new machine. It proves which conversion backend the runtime will execute; the presence of the monodoc binary alone does not prove that conversion is ready.

​
Published Command Surface

The current public build has 6 operational root commands plus help and version aliases.
monodoc search is not file-scoped in this release. It calls the general Monomento search API and labels each result with its actual doc_type. Use the result labels, or query Monomento directly when source filtering matters.

​
Parser and Automation Boundary

MonoDoc uses a hand-written root dispatcher. There is no command-specific help surface or general subcommand flag parser:
Only the first positional file or directory is consumed by convert, index, and index-dir. Quote paths that contain spaces. For readiness automation, parse the text from which; do not treat exit code zero as proof that markitdown was found.
Repository HEAD contains a docs [topic] dispatcher for a future build. The immutable 0.1.1 / 2026-04-27-191303 payload rejects docs with a non-zero exit, so the command is not part of the current public contract.

​
Conversion Backend

Runtime resolution is ordered and stops at the first match:
  1. markitdown on PATH (markitdown.exe on Windows);
  2. ~/.monolex/bin/markitdown;
  3. a companion binary adjacent to the running monodoc executable.
The public CDN release metadata lists markitdown/markitdown.exe alongside monodoc/monodoc.exe. Runtime resolution still remains authoritative: check monodoc which after installation instead of assuming a particular placement. MonoDoc forwards two environment surfaces to the subprocess:
  • OPENAI_API_KEY, for backend features such as image description or OCR when the installed MarkItDown build supports them;
  • PATH, so companion programs such as ffmpeg can be discovered.
Conversion quality and optional capabilities belong to the selected backend. MonoDoc captures stdout as UTF-8 and returns a non-zero exit if the backend process fails or emits invalid UTF-8.

​
Supported Inputs

The CLI’s recursive directory filter is a hard-coded extension allowlist. The allowlist controls index-dir; direct convert and index pass the specified file to the backend. A listed extension is not a guarantee that every file of that type will convert successfully.

​
Bulk Index Semantics

index-dir recursively collects supported files, skips directories whose names start with ., opens one database transaction, then processes each file. An individual failure increments Errors and processing continues. Successful documents are committed at the end, so this is a partial-success batch, not an all-or-nothing import. Each document replacement itself uses a Monomento savepoint. Unchanged content at the same stored path is skipped. MonoDoc stores the path text it was given rather than canonicalizing it, so different lexical aliases can produce separate rows.

​
Storage and Read/Write Boundary

Monomento resolves the shared database through MONOMENTO_HOME, the current ~/.monolex/monomento.db, and then the legacy Monolex application-support path. list, search, and which do not write the index, although search is cross-source as noted above.

​
Published Platforms

The public 0.1.1 metadata does not contain a Windows ARM64 artifact.

​
Relationships