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

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 30-45, 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 60-63 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. 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, 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 31-33 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 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:

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

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

# 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	Canonical definition of plugin kinds, manifest schema, and IPC protocol 30-45
src/officecli/Core/Plugins/PluginRegistry.cs	Filesystem scanning, manifest parsing, caching, and protocol version validation 31-33
src/officecli/Handlers/DocumentHandlerFactory.cs	Central dispatcher selecting native handlers, dump-readers, or format-handlers 60-63
src/officecli/Core/Plugins/FormatHandlerSession.cs	Manages long-lived format-handler processes and JSON request/response cycles
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.
• DocumentHandlerFactory.cs and 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 30-45, 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 60-63, 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: 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 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, this one-shot conversion avoids disk overhead and temporary file cleanup.

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