> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # MonoDoc > Convert local documents and media to Markdown, index them, and search the shared Monomento knowledge layer. 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](/ai-clis/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 ```bash theme={null} openclis install monodoc monodoc --version monodoc which monodoc convert report.pdf > report.md monodoc index report.pdf ``` 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. | Command | Reads | Writes | Contract | | ---------------------------- | --------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- | | `convert ` | One local file and the conversion backend | Nothing persistent | Prints Markdown to stdout. | | `index ` | One local file and the backend | One `file` document and its search records | Prints title, path, word count, and new/unchanged status. | | `index-dir ` | A recursive directory walk and every supported file found | Successful documents and search records | Skips hidden directories, continues after individual conversion errors, and reports totals. | | `list` | Shared Monomento database | Nothing | Lists only `doc_type=file` rows. | | `search ` | Shared Monomento search index | Nothing | Returns up to 10 results across **all document types**, not only local files. | | `which` | PATH and two fallback locations | Nothing | Prints the selected backend or `NOT FOUND`; both outcomes currently exit zero. | | `help`, `--help`, `-h` | Embedded root guide | Nothing | Prints the same root guide as bare `monodoc`. | | `version`, `--version`, `-v` | Package identity | Nothing | Prints `monodoc 0.1.1`. | `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: ```bash theme={null} monodoc help index # prints the root guide monodoc index --help # treats --help as a filename ``` 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. | Family | Extensions | | ---------------------- | -------------------------------------------- | | Documents | `pdf`, `docx`, `pptx`, `xlsx`, `xls`, `epub` | | Web and feeds | `html`, `htm`, `xml`, `rss`, `atom` | | Data | `csv`, `json` | | Images | `jpg`, `jpeg`, `png`, `gif`, `bmp`, `tiff` | | Audio | `wav`, `mp3`, `m4a` | | Archives and notebooks | `zip`, `ipynb` | | Text and mail | `txt`, `md`, `msg` | 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 ```text theme={null} local file or directory ↓ markitdown subprocess ├── convert → stdout only └── index / index-dir → shared Monomento database (`doc_type=file`) ``` 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 | Platform | Package binaries | | ------------------- | ------------------------------- | | macOS Apple Silicon | `monodoc`, `markitdown` | | macOS Intel | `monodoc`, `markitdown` | | Linux ARM64 | `monodoc`, `markitdown` | | Linux x86-64 | `monodoc`, `markitdown` | | Windows x86-64 | `monodoc.exe`, `markitdown.exe` | The public `0.1.1` metadata does **not** contain a Windows ARM64 artifact. ## Relationships | Use case | Companion | | ------------------------------------------------ | ------------------------------- | | Convert or index local files | **MonoDoc** | | Fetch a static web page or docs sitemap | [MonoFetch](/ai-clis/monofetch) | | Import an OpenAPI definition | [MonoAPI](/ai-clis/monoapi) | | Search and read the shared corpus | [Monomento](/ai-clis/monomento) | | Join document evidence with code and git history | [MonoFlow](/ai-clis/monoflow) |