# OfficeCLI Plugin System: Extending Support for .doc, .hwpx, and PDF Export > Learn how the OfficeCLI plugin system adds .doc, .hwpx, and PDF export support using dump-reader, format-handler, and exporter plugins, keeping the core binary efficient. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-07-31 --- **The OfficeCLI plugin system extends format support through three specialized plugin kinds—dump-reader for legacy formats like .doc, format-handler for regional formats like .hwpx, and exporter for PDF conversion—allowing the core binary to remain lightweight while handling diverse document types via external plugins.** OfficeCLI natively supports the three core OOXML formats (`.docx`, `.xlsx`, `.pptx`), but delegates all other file types to its modular plugin architecture. Through the **OfficeCLI Plugin Protocol** (v1), developers can extend the CLI to read legacy word processors, edit regional document standards, and export to fixed-layout formats without modifying the core codebase. ## The Three Plugin Kinds The protocol defines three distinct plugin kinds, each designed for a specific workflow. When OfficeCLI encounters a file extension it does not handle natively, it consults [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs) to determine which plugin kind to invoke based on the file type and operation. ### Dump-Reader Plugins for Legacy Formats **Dump-reader** plugins handle one-way conversion of legacy or foreign formats into native OOXML. These plugins declare a source extension (such as `.doc`) and a target native format (such as `docx`). When a user opens a `.doc` file, OfficeCLI spawns the registered dump-reader plugin and executes ` dump `. The plugin streams JSONL batch commands to stdout that recreate the document structure, which OfficeCLI replays into a cached `.docx` sibling. According to the protocol specification in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) [lines 30-45](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L30-L45), this approach isolates legacy parsing logic from the core binary. ### Format-Handler Plugins for Regional Formats **Format-handler** plugins provide first-class, session-based support for non-native formats like **.hwpx** (Hangul Word Processor). Unlike dump-readers, format-handlers own the document for the entire editing session and expose a full command vocabulary. The plugin launches with `open ` and remains alive, communicating over stdin/stdout via JSON envelopes. All subsequent commands (`get`, `set`, `add`) route through [`FormatHandlerSession.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/FormatHandlerSession.cs), which manages the request/response protocol. During initialization, the plugin reports its capabilities through an *open handshake* defined in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) [lines 95-110](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L95-L110), enabling the CLI to autocomplete properties specific to the `.hwpx` model. ### Exporter Plugins for PDF Output **Exporter** plugins convert native OOXML files into foreign output formats such as **PDF**. This design keeps the core binary small while supporting complex rendering operations. When exporting, OfficeCLI resolves the appropriate exporter plugin for the target extension (`.pdf`) and spawns ` export --out `. The exporter reads the native file in read-only mode and writes the output directly. As documented in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) [lines 67-88](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L67-L88), this workflow performs a pure one-shot conversion without creating intermediate files. ## Plugin Discovery and Resolution OfficeCLI locates plugins through a prioritized search order implemented in [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs) [lines 30-35](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Plugins/PluginRegistry.cs#L30-L35). The resolver checks: 1. Environment variables 2. User plugins directory 3. Bundled plugins directory 4. System PATH [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs) handles manifest parsing, caching, and protocol version validation. When [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs) [lines 60-63](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/DocumentHandlerFactory.cs#L60-L63) receives a request for a non-native format, it queries the registry for a matching `(kind, ext)` pair. The first valid plugin wins, making installation as simple as placing the executable in the user plugins folder or running `officecli plugins install`. ## Practical Usage Examples ### Converting Legacy .doc Files Install the official dump-reader plugin to enable `.doc` support: ```bash # Install the .doc to .docx converter officecli plugins install officecli-doc # Open a legacy Word file; OfficeCLI automatically invokes the plugin, # generates a sibling .docx, and renders it officecli view report.doc ``` Behind the scenes, `DocumentHandlerFactory` detects the `.doc` extension, locates the dump-reader, and replays the emitted batch commands into a native temporary file. ### Editing .hwpx Files Directly Install the format-handler plugin for Hangul Word Processor support: ```bash # Install the regional format handler officecli plugins install officecli-hwpx # Read and modify a Hangul document officecli get manuscript.hwpx /body/p[1] --json officecli set manuscript.hwpx /body/p[1] --prop text="새로운 텍스트" officecli save manuscript.hwpx ``` The `officecli-hwpx` plugin maintains a persistent session managed by [`FormatHandlerSession.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/FormatHandlerSession.cs), translating CLI commands into the native `.hwpx` object model. ### Exporting to PDF Install an exporter plugin to generate PDFs from any native OOXML file: ```bash # Install the PDF exporter officecli plugins install officecli-pdf # Convert presentations and spreadsheets officecli view deck.pptx pdf --out deck.pdf officecli view budget.xlsx pdf --out budget.pdf ``` The exporter reads the source file read-only and streams the PDF output, with CLI entry points defined in [`CommandBuilder.Plugins.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Plugins.cs). ## Summary - **Three plugin kinds** handle all non-native formats: dump-readers for legacy import, format-handlers for regional editing, and exporters for PDF generation. - **Dump-reader** plugins stream batch commands to convert `.doc` files into native `.docx` format on the fly. - **Format-handler** plugins maintain long-lived sessions for formats like `.hwpx`, exposing full read/write capabilities via JSON IPC. - **Exporter** plugins perform one-shot conversions from OOXML to PDF without intermediate files. - **Discovery** follows a strict hierarchy (env-var → user → bundled → PATH) implemented in [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs). - **Resolution** logic in [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs) automatically selects the appropriate handler based on file extension and requested operation. ## Frequently Asked Questions ### What is the OfficeCLI Plugin Protocol? The **OfficeCLI Plugin Protocol** (v1) is a specification that defines how external executables integrate with OfficeCLI. It standardizes three plugin kinds (dump-reader, format-handler, exporter), manifest schemas, and IPC mechanisms over stdin/stdout. The canonical definition resides in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md). ### How does OfficeCLI open .doc files without native support? OfficeCLI uses a **dump-reader** plugin to handle `.doc` files. When you open a legacy Word document, the CLI spawns the registered plugin, which parses the binary format and streams JSONL batch commands to recreate the document as a native `.docx`. OfficeCLI caches this conversion temporarily, allowing seamless viewing and editing. ### What is the difference between a dump-reader and a format-handler? A **dump-reader** performs one-way conversion from a foreign format to native OOXML and then exits, making it suitable for legacy formats like `.doc`. A **format-handler** stays resident for the entire session, maintaining state and handling bidirectional synchronization for formats like `.hwpx` that require full editing capabilities and specialized command vocabularies. ### Where does OfficeCLI search for installed plugins? OfficeCLI searches for plugins in a specific order defined in [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs): first environment variables, then the user plugins directory, followed by bundled plugins, and finally the system PATH. You can install plugins manually by placing them in these directories or use the `officecli plugins install` command managed by [`CommandBuilder.Plugins.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Plugins.cs).