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

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:

{"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.

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—all subsequent get, set, add, and save commands flow as JSON envelopes over stdin/stdout.

This architecture lets users edit .hwpx files directly:

# 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. When you request PDF output, OfficeCLI resolves the exporter plugin for .pdf and invokes:

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

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

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

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 lines 30-35: Handles filesystem scanning, manifest parsing, version compatibility checking, and result caching.

• DocumentHandlerFactory.cs lines 60-63: 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: Provides the officecli plugins CLI subcommands for installation, listing, and validation.

• FormatHandlerSession.cs: Manages long-lived format-handler processes, handling JSON request/response cycles over process streams.

Complete Workflow Examples

Adding .doc Support

# 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

# 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

# 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 and dispatched by DocumentHandlerFactory.cs.

• All plugin behavior is governed by the OfficeCLI Plugin Protocol v1, documented in 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 for the complete specification.

How does OfficeCLI handle plugin version conflicts?

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.

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