# How the OfficeCLI Plugin System Extends Support for .doc, .hwpx, and PDF Export > Discover how the OfficeCLI plugin system easily adds support for .doc, .hwpx, and PDF export, keeping the core binary lean with specialized external processes. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-07-11 --- **The OfficeCLI plugin system extends format support through three distinct plugin types—`dump‑reader` for legacy formats like `.doc`, `format‑handler` for regional standards like `.hwpx`, and `exporter` for PDF conversion—allowing the core binary to remain lean while delegating non-native document operations to specialized external processes.** The OfficeCLI plugin system powers the iOfficeAI/OfficeCLI repository’s ability to handle document formats beyond the native OOXML trio (`.docx`, `.xlsx`, `.pptx`). By implementing the OfficeCli Plugin Protocol (v1), the architecture delegates format-specific processing to external plugins, enabling the CLI to open legacy Word files, edit Hangul documents, and export to PDF without recompiling the core binary. ## The Three Plugin Architecture Types The OfficeCLI plugin system defines three distinct plugin kinds, each designed for a specific conversion workflow. ### Dump-Reader Plugins for Legacy Formats (.doc) **Dump‑reader** plugins convert foreign source files into OfficeCLI batch commands that recreate the document in a native OOXML format. When opening a `.doc` file, OfficeCLI spawns the registered dump‑reader plugin, which streams JSONL batch items (e.g., `{"command":"add","parent":"/body","type":"paragraph",...}`) to generate a sibling `.docx` file cached for subsequent operations. According to [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) (lines 30–45), the plugin declares its source extension (`.doc`) and target native format (`docx`), allowing the system to invoke the correct translator automatically. ### Format-Handler Plugins for Regional Formats (.hwpx) **Format‑handler** plugins provide first-class support for non-native formats by owning the document for the entire session. Unlike dump-readers, these plugins implement a full command vocabulary (`add`, `set`, `get`, etc.) over stdin/stdout, enabling direct editing of formats like `.hwpx` (Hangul Word Processor). The plugin reports its capabilities via the *open handshake* described in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) (lines 95–110), allowing the CLI to autocomplete properties specific to the Hangul format model. ### Exporter Plugins for PDF Output **Exporter** plugins handle one-way conversion from native OOXML formats to foreign output formats like PDF. The exporter reads the native file (`.docx`, `.xlsx`, or `.pptx`) read-only and writes the target `.pdf` without creating intermediate files. This workflow is defined in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) (lines 67–88), ensuring that PDF generation occurs as a pure one-shot conversion operation. ## Plugin Discovery and Resolution When OfficeCLI requires a plugin for a specific `(kind, ext)` pair, it follows a fixed resolution order defined in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) (lines 34–47): 1. Environment variable lookup 2. User-plugins directory 3. Bundled plugins directory 4. System PATH The first match wins. The **[`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs)** file (lines 30–35) implements this scanning logic, handling manifest parsing and protocol version compatibility, while **[`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs)** (lines 60–63) acts as the central dispatcher, choosing between native handlers, dump-readers, or format-handlers based on the file extension. ## Working with Plugins: Code Examples ### Adding .doc Support (Dump-Reader) ```bash # Install the official .doc → .docx dump-reader plugin officecli plugins install officecli-doc # Open a legacy Word file; OfficeCLI automatically invokes the plugin, # produces a sibling .docx, and works with it as native officecli view report.doc ``` **What happens:** `DocumentHandlerFactory` detects the `.doc` extension and locates the dump-reader plugin. The plugin executes ` dump report.doc`, streams batch commands, and OfficeCLI replays them into `report.docx`, caching the result. ### Adding .hwpx Support (Format-Handler) ```bash # Install the Hangul Word Processor format-handler officecli plugins install officecli-hwpx # Edit a Hangul document directly using the plugin's command vocabulary officecli get manuscript.hwpx /body/p[1] --json officecli set manuscript.hwpx /body/p[1] --prop text="새로운 텍스트" officecli save manuscript.hwpx ``` **What happens:** The format-handler launches with `open ` and remains alive for the session. All subsequent commands travel as JSON envelopes over stdin/stdout, with **[`FormatHandlerSession.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/FormatHandlerSession.cs)** managing the long-lived process and request/response protocol. ### Exporting to PDF (Exporter) ```bash # Install the PDF exporter plugin officecli plugins install officecli-pdf # Export native OOXML files to PDF officecli view deck.pptx pdf --out deck.pdf officecli view budget.xlsx pdf --out budget.pdf ``` **What happens:** OfficeCLI resolves the `exporter` plugin for the `.pdf` extension, spawns ` export --out `, and performs the conversion without modifying the source OOXML file. ## Core Implementation Files The OfficeCLI plugin system relies on these key source files: - **[`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md)** – Canonical definition of the three plugin kinds, manifest schema, discovery rules, and IPC details. - **[`src/officecli/Core/Plugins/PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Plugins/PluginRegistry.cs)** – Scans the filesystem, parses plugin manifests, caches results, and enforces protocol version compatibility. - **[`src/officecli/Handlers/DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/DocumentHandlerFactory.cs)** – Central dispatcher that selects native handlers, dump-reader plugins, or format-handler plugins based on file extension. - **[`src/officecli/Core/Plugins/FormatHandlerSession.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Plugins/FormatHandlerSession.cs)** – Manages long-lived format-handler processes, handling the JSON request/response protocol over stdin/stdout. - **[`src/officecli/CommandBuilder.Plugins.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Plugins.cs)** – CLI entry point (`officecli plugins …`) for installing, listing, and validating plugins. ## Summary - **Three plugin kinds** extend OfficeCLI: `dump‑reader` for legacy import (`.doc`), `format‑handler` for regional editing (`.hwpx`), and `exporter` for PDF conversion. - **Automatic resolution** follows a fixed search order (env-var → user → bundled → PATH) implemented in [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs). - **Zero core bloat** – plugins run as external processes, keeping the main binary small while supporting diverse formats. - **Protocol-based communication** uses JSON over stdin/stdout, with specific workflows defined in [`plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugin-protocol.md). ## Frequently Asked Questions ### How does OfficeCLI open .doc files without native support? OfficeCLI uses a `dump‑reader` plugin that converts the legacy `.doc` binary into a stream of batch commands. These commands recreate the document as a native `.docx` file, which OfficeCLI then caches and treats as the working document. The process is transparent to the user and occurs automatically when the plugin is installed. ### What is the difference between a dump-reader and a format-handler plugin? A **dump‑reader** performs one-time conversion from a foreign format to OOXML, after which the plugin exits and OfficeCLI works with the generated native file. A **format‑handler** remains active for the entire session, maintaining its own document model and exposing a custom command vocabulary for direct editing of the non-native format (such as `.hwpx`). ### Where does OfficeCLI search for installed plugins? The system searches in a specific priority order: environment variables first, then the user-plugins directory, followed by bundled plugins, and finally the system PATH. This discovery mechanism is implemented in [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs) and documented in [`plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugin-protocol.md) (lines 34–47). ### Can I create a custom exporter for formats other than PDF? Yes. The `exporter` plugin kind is designed for any one-way conversion from native OOXML to a foreign output format. By implementing the exporter protocol defined in [`plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugin-protocol.md) (lines 67–88), developers can add support for formats like ODT, RTF, or XPS without modifying the OfficeCLI core binary.