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

> Discover how OfficeCLI's plugin system enhances format support for .doc, .hwpx, and PDF exports. Learn about dump-readers, format-handlers, and exporters for seamless conversions.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-10

---

**OfficeCLI extends beyond its three native OOXML formats through a plugin protocol that defines three specialized plugin kinds—dump-reader, format-handler, and exporter—each handling distinct conversion workflows for legacy, regional, and output formats.**

The **OfficeCLI** command-line tool ships with first-class support for `.docx`, `.xlsx`, and `.pptx` files. Every other format—whether importing legacy Word documents, editing regional Hangul files, or exporting to PDF—relies on the **OfficeCLI Plugin Protocol (v1)**. This protocol establishes a clean boundary between the lean core binary and pluggable extensions that add format capabilities without recompiling.

## The Three Plugin Kinds in OfficeCLI

The protocol defines three plugin **kinds**, each mapping to a specific technical workflow. Understanding these kinds explains exactly how OfficeCLI handles non-native formats.

### Dump-Reader Plugins: Importing Legacy Formats Like .doc

**Dump-reader plugins** convert foreign source files into native OOXML by streaming batch commands.

When you open a `.doc` file, OfficeCLI spawns the registered dump-reader plugin, which executes `<plugin> dump <source>`. The plugin outputs a JSONL stream of document reconstruction commands—for example:

```json
{"command":"add","parent":"/body","type":"paragraph","props":{"text":"Legacy content"}}

```

OfficeCLI replays these commands into a sibling `.docx` file, then caches that native version for subsequent operations. The plugin declares its source extension (`.doc`) and target format (`docx`) in its manifest, as defined in the protocol specification [lines 30-45](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L30-L45).

**Key characteristic:** The dump-reader runs once per conversion, then exits. The resulting `.docx` becomes the working document.

### Format-Handler Plugins: Native-Style Support for .hwpx

**Format-handler plugins** provide full-session ownership of non-native formats, enabling true read/write support for formats like `.hwpx` (Hangul Word Processor).

Unlike dump-readers, format-handlers stay alive for the entire editing session. After the **open handshake**—where the plugin reports its command vocabulary and capabilities [lines 95-110](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L95-L110)—all subsequent `get`, `set`, `add`, and `save` commands flow as JSON envelopes over stdin/stdout.

This architecture lets users edit `.hwpx` files directly:

```bash

# Install the Hangul Word Processor plugin

officecli plugins install officecli-hwpx

# Query and modify content using standard CLI commands

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

```

The format-handler flushes changes on `save`, maintaining the original `.hwpx` format throughout.

### Exporter Plugins: PDF and Other Output Formats

**Exporter plugins** convert native OOXML files into foreign output formats such as PDF.

These plugins implement one-shot, read-only conversion workflows [lines 67-88](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L67-L88). When you request PDF output, OfficeCLI resolves the `exporter` plugin for `.pdf` and invokes:

```bash
<plugin> export <source> --out <target>

```

The exporter reads the native file directly—no intermediate conversion to `.docx` occurs—and writes the final PDF:

```bash

# Install the PDF exporter

officecli plugins install officecli-pdf

# Export presentations and spreadsheets

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

```

## How OfficeCLI Discovers and Resolves Plugins

Plugin resolution follows a strict search order for any `(kind, ext)` pair [lines 34-47](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md#L34-L47):

1. Environment variable override
2. User plugins directory
3. Bundled plugins directory
4. System PATH

The first match wins. This hierarchy allows users to override bundled plugins with custom versions or install new formats system-wide.

Two core files orchestrate this process:

- **[`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): Handles filesystem scanning, manifest parsing, version compatibility checking, and result caching.

- **[`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): The central dispatcher that chooses between native handlers, dump-reader plugins, and format-handler plugins based on file extension and requested operation.

Additional implementation files include:

- **[`CommandBuilder.Plugins.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Plugins.cs)**: Provides the `officecli plugins` CLI subcommands for installation, listing, and validation.

- **[`FormatHandlerSession.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/FormatHandlerSession.cs)**: Manages long-lived format-handler processes, handling JSON request/response cycles over process streams.

## Complete Workflow Examples

### Adding .doc Support

```bash

# Install the official .doc → .docx converter

officecli plugins install officecli-doc

# Open legacy Word files transparently

officecli view report.doc

```

Behind the scenes: `DocumentHandlerFactory` detects `.doc`, locates the `dump-reader` plugin, executes the dump, replays the batch into `report.docx`, and proceeds with native rendering.

### Adding .hwpx Support

```bash

# Install Hangul Word Processor support

officecli plugins install officecli-hwpx

# Edit with full command vocabulary

officecli set manuscript.hwpx /body/p[2] --prop font-size=14
officecli save manuscript.hwpx

```

The format-handler process persists, translating OfficeCLI commands into `.hwpx` native operations.

### Adding PDF Export

```bash

# Install PDF export capability

officecli plugins install officecli-pdf

# Generate PDF from any native format

officecli view analysis.xlsx pdf --out analysis.pdf

```

The exporter plugin reads the `.xlsx` directly and produces the PDF without creating intermediate files.

## Summary

- **Three plugin kinds** define OfficeCLI's extension model: `dump-reader` for import conversion, `format-handler` for full-session editing, and `exporter` for output generation.

- **Legacy .doc support** uses dump-readers that stream reconstruction commands into cached `.docx` files.

- **Regional .hwpx support** uses format-handlers that maintain long-lived sessions with their own command vocabularies.

- **PDF export** uses exporters that perform one-shot, read-only conversions from native OOXML.

- **Plugin resolution** follows environment → user → bundled → PATH precedence, managed by [`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs) and dispatched by [`DocumentHandlerFactory.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/DocumentHandlerFactory.cs).

- All plugin behavior is governed by the **OfficeCLI Plugin Protocol v1**, documented in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md).

## Frequently Asked Questions

### What formats does OfficeCLI support without plugins?

OfficeCLI supports `.docx`, `.xlsx`, and `.pptx` natively. All other formats—including `.doc`, `.hwpx`, and PDF export—require installing the appropriate plugin.

### Can I write my own plugin for a custom file format?

Yes. Any executable implementing the OfficeCLI Plugin Protocol v1 can register as a plugin. You must choose the appropriate kind (`dump-reader`, `format-handler`, or `exporter`), implement the required command interface, and provide a valid manifest. See [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) for the complete specification.

### How does OfficeCLI handle plugin version conflicts?

[`PluginRegistry.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PluginRegistry.cs) enforces protocol version compatibility during discovery. Plugins declare their protocol version in their manifest; incompatible versions are rejected with a validation error. The first compatible plugin found in the resolution order (environment, user, bundled, PATH) is loaded.

### Is PDF export available on all platforms?

PDF export depends on the platform-specific `officecli-pdf` plugin implementation. The core OfficeCLI binary remains platform-agnostic, but individual plugins may have platform requirements. Check the plugin's manifest and documentation for supported operating systems.