# How the OfficeCLI Plugin System Extends Support for .doc, .hwpx, and PDF Export

> Discover how the OfficeCLI plugin system adds support for .doc, .hwpx, and PDF export. Learn about the dump-reader, format-handler, and exporter plugins.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-07-21

---

**The OfficeCLI plugin system extends support for legacy .doc files, Hangul .hwpx documents, and PDF export through three specialized plugin kinds—dump-reader, format-handler, and exporter—defined by the OfficeCli Plugin Protocol v1.**

The iOfficeAI/OfficeCLI repository handles `.docx`, `.xlsx`, and `.pptx` natively, but relies on its extensible plugin architecture to work with legacy and regional formats. By implementing the OfficeCLI plugin system, developers can add support for binary Word documents, Korean word processor files, and export to PDF without modifying the core binary.

## The Three Plugin Kinds in the OfficeCLI Plugin Protocol

The **OfficeCli Plugin Protocol (v1)** defines three distinct plugin kinds, each designed for a specific workflow when bridging non-native formats. According to the protocol specification in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) [30-45](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L30-L45), these kinds determine how the CLI interacts with external file types.

### Dump-Reader Plugins for Legacy Formats (.doc)

**Dump-reader** plugins translate foreign source files into native OOXML by streaming batch commands. When opening a `.doc` file, OfficeCLI spawns the dump-reader plugin, which emits JSONL batch items that recreate the document structure as a `.docx` sibling.

This approach caches the converted native file for subsequent operations. The plugin declares its source extension (`.doc`) and target native format (`docx`) in its manifest, enabling [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs) [60-63](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/DocumentHandlerFactory.cs#L60-L63) to route legacy files through the appropriate translation layer.

### 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. Instead of converting to OOXML, the plugin implements a full command vocabulary (`add`, `set`, `get`, etc.) over stdin/stdout.

For `.hwpx` (Hangul Word Processor) files, the plugin stays alive during the session, responding to JSON envelopes and reporting its capabilities via the open handshake [95-110](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L95-L110). This allows the CLI to offer autocomplete and direct manipulation without intermediate conversion.

### Exporter Plugins for PDF Output

**Exporter** plugins handle one-way conversion from native OOXML to foreign output formats. The PDF exporter reads `.docx`, `.xlsx`, or `.pptx` files in read-only mode and writes the target `.pdf` without creating intermediate files or bloating the core binary.

The workflow is defined in the protocol [67-88](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L67-L88), where the CLI resolves the exporter based on the target extension and spawns the plugin with `export <source> --out <target>` arguments.

## Plugin Discovery and Resolution Strategy

When OfficeCLI requires a plugin for a specific `(kind, ext)` pair, [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs) [31-33](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Plugins/PluginRegistry.cs#L30-L35) executes a fixed search order:

1. **Environment variables** (`OFFICECLI_PLUGIN_PATH`)
2. **User plugins** directory
3. **Bundled plugins** shipped with the CLI
4. **System PATH** scanning

The first match wins, and the registry caches validated manifests to avoid filesystem overhead on subsequent calls. [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs) then selects the appropriate handler—native, dump-reader, or format-handler—based on the resolved plugin metadata and file extension.

## Practical Examples: Extending OfficeCLI for New Formats

The OfficeCLI plugin system enables zero-downtime format support through simple installation commands. Below are concrete implementations for the three extension types.

### Opening Legacy Word Documents (.doc)

Install the official dump-reader to enable `.doc` support:

```bash

# Install the .doc → .docx dump-reader plugin

officecli plugins install officecli-doc

# Open a legacy Word file; CLI automatically invokes the plugin

officecli view report.doc

```

**Implementation details:**

- `DocumentHandlerFactory` detects the `.doc` extension and locates the dump-reader plugin
- The plugin executes `<plugin> dump report.doc` and streams JSONL batch commands (e.g., `{"command":"add","parent":"/body","type":"paragraph"}`)
- OfficeCLI replays the batch into `report.docx`, caching the sibling for future operations

### Editing Hangul Word Processor Files (.hwpx)

Install the format-handler for true `.hwpx` support:

```bash

# Install the Hangul Word Processor format-handler

officecli plugins install officecli-hwpx

# Directly manipulate the document structure

officecli get manuscript.hwpx /body/p[1] --json
officecli set manuscript.hwpx /body/p[1] --prop text="새로운 텍스트"
officecli save manuscript.hwpx

```

**Implementation details:**

- [`FormatHandlerSession.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/FormatHandlerSession.cs) launches the plugin with `open <file>` and maintains the process for the session duration
- Commands are serialized as JSON envelopes over stdin/stdout
- The plugin's vocabulary, reported during the open handshake, enables property autocompletion for the `.hwpx` document model

### Converting Presentations and Spreadsheets to PDF

Install the exporter for PDF output capabilities:

```bash

# Install the PDF exporter plugin

officecli plugins install officecli-pdf

# Export native formats to PDF

officecli view deck.pptx pdf --out deck.pdf
officecli view budget.xlsx pdf --out budget.pdf

```

**Implementation details:**

- CLI resolves the `exporter` kind for the `.pdf` extension
- Spawns `<plugin> export <source> --out <target>` with read-only access to the native file
- Performs pure one-shot conversion without intermediate OOXML generation

## Key Source Files and Implementation Details

The extensibility of the OfficeCLI plugin system relies on specific source files that handle discovery, session management, and command dispatching:

| File | Role |
|------|------|
| [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) | Canonical definition of plugin kinds, manifest schema, and IPC protocol [30-45](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L30-L45) |
| [`src/officecli/Core/Plugins/PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Plugins/PluginRegistry.cs) | Filesystem scanning, manifest parsing, caching, and protocol version validation [31-33](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Plugins/PluginRegistry.cs#L30-L35) |
| [`src/officecli/Handlers/DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/DocumentHandlerFactory.cs) | Central dispatcher selecting native handlers, dump-readers, or format-handlers [60-63](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/DocumentHandlerFactory.cs#L60-L63) |
| [`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 and JSON request/response cycles |
| [`src/officecli/CommandBuilder.Plugins.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Plugins.cs) | CLI entry point for `officecli plugins install/list` operations |

## Summary

- The **OfficeCLI plugin system** uses three specialized kinds—**dump-reader**, **format-handler**, and **exporter**—to extend format support without core binary changes.
- **Dump-readers** (used for `.doc`) convert legacy files to OOXML by streaming batch commands, while **format-handlers** (used for `.hwpx`) provide native-like command vocabularies for regional formats.
- **Exporters** enable PDF output by reading native files and writing target formats in one-shot operations.
- Plugin resolution follows a strict hierarchy: environment variables → user directory → bundled plugins → PATH, managed by [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs).
- [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs) and [`FormatHandlerSession.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/FormatHandlerSession.cs) coordinate between the CLI core and plugin processes via JSON IPC.

## Frequently Asked Questions

### What is the OfficeCLI Plugin Protocol v1?

The OfficeCLI Plugin Protocol v1 is a specification that defines how external binaries integrate with OfficeCLI through standardized stdin/stdout communication. It establishes three plugin kinds (dump-reader, format-handler, exporter), manifest schemas, and discovery rules. According to [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) [30-45](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L30-L45), compliant plugins declare their supported extensions and target formats in JSON manifests, enabling the CLI to resolve appropriate handlers for non-native file types.

### How does OfficeCLI handle legacy .doc files differently from .hwpx files?

OfficeCLI processes `.doc` files using **dump-reader** plugins that translate the binary format into OOXML batch commands and cache a converted `.docx` sibling. In contrast, `.hwpx` files utilize **format-handler** plugins that maintain a persistent session, implementing direct commands like `get` and `set` without intermediate conversion. The distinction is handled in [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs) [60-63](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/DocumentHandlerFactory.cs#L60-L63), which routes `.doc` to translation workflows and `.hwpx` to live session management.

### Where does OfficeCLI search for installed plugins?

The CLI follows a fixed resolution order defined in the protocol [34-47](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L34-L47): first checking the `OFFICECLI_PLUGIN_PATH` environment variable, then the user plugins directory, followed by bundled plugins shipped with the binary, and finally scanning the system PATH. [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs) implements this hierarchy, caching the first valid manifest found to optimize subsequent file operations.

### Can OfficeCLI export to PDF without creating intermediate files?

Yes. The **exporter** plugin kind performs direct conversion without generating intermediate OOXML files. When exporting to PDF, OfficeCLI spawns the exporter plugin with read-only access to the native source file, and the plugin writes the PDF output directly. As implemented in the protocol [67-88](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L67-L88), this one-shot conversion avoids disk overhead and temporary file cleanup.