OfficeCLI Plugin System: Extending Support for .doc, .hwpx, and PDF Export

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 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 <plugin> dump <file>. 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 lines 30-45, 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 <file> and remains alive, communicating over stdin/stdout via JSON envelopes. All subsequent commands (get, set, add) route through 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 lines 95-110, 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 <plugin> export <source> --out <target>. The exporter reads the native file in read-only mode and writes the output directly. As documented in plugins/plugin-protocol.md lines 67-88, 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 lines 30-35. The resolver checks:

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

PluginRegistry.cs handles manifest parsing, caching, and protocol version validation. When DocumentHandlerFactory.cs lines 60-63 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:

# 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:

# 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, translating CLI commands into the native .hwpx object model.

Exporting to PDF

Install an exporter plugin to generate PDFs from any native OOXML file:

# 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.

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.
• Resolution logic in 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.

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: 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}