hwpilot

hwpilot

Native HWP/HWPX document editor for AI agents. Read, edit, and create Korean word processor documents without format conversion. All commands output JSON.

Quick Start

# Read document structure
hwpilot read document.hwpx

# Extract text from a specific paragraph
hwpilot text document.hwpx s0.p0

# Edit text in-place
hwpilot edit text document.hwpx s0.p0 "Updated content"

# Read a table
hwpilot table read document.hwpx s0.t0

# Convert legacy HWP to editable HWPX
hwpilot convert legacy.hwp output.hwpx

Reference System

Documents use hierarchical refs to address elements. All indices are 0-based.

Ref Pattern	Target	Example
s{N}	Section N	s0
s{N}.p{M}	Paragraph M in section N	s0.p0
s{N}.p{M}.r{K}	Run K in paragraph M	s0.p2.r1
s{N}.t{M}	Table M in section N	s0.t0
s{N}.t{M}.r{R}.c{C}	Row R, cell C of table M	s0.t1.r2.c0
s{N}.t{M}.r{R}.c{C}.p{P}	Paragraph P inside table cell	s0.t0.r0.c0.p0
s{N}.tb{M}	Text box M in section N	s0.tb0
s{N}.tb{M}.p{P}	Paragraph P inside text box M	s0.tb0.p0
s{N}.img{M}	Image M in section N	s0.img0

A "run" is a contiguous span of text sharing the same character formatting within a paragraph. Most paragraphs have a single run (r0).

Ref Examples

• s0 ... first section (all paragraphs, tables, images)
• s0.p0 ... first paragraph of first section
• s0.t0.r1.c2 ... table 0, row 1, cell 2
• s0.t0.r0.c0.p0 ... first paragraph inside a table cell
• s0.tb0 ... first text box in section 0
• s0.tb0.p0 ... first paragraph inside text box 0
• s0.img0 ... first image in section 0

Command Reference

hwpilot read ... Read document structure

hwpilot read <file> [ref] [--offset <n>] [--limit <n>] [--pretty]

Without a ref, returns the full document tree. With a ref, returns that specific element. Use --offset and --limit to paginate paragraphs and reduce output size.

Option	Effect
--offset <n>	Skip first N paragraphs (0-indexed)
--limit <n>	Return at most N paragraphs

# First 20 paragraphs
hwpilot read report.hwpx --limit 20

# Paragraphs 20–39
hwpilot read report.hwpx --offset 20 --limit 20

# Single paragraph by ref (no pagination needed)
hwpilot read report.hwpx s0.p0

# A table
hwpilot read report.hwpx s0.t0

Example output (with pagination):

{
  "format": "hwpx",
  "sections": [{
    "index": 0,
    "totalParagraphs": 50,
    "totalTables": 2,
    "totalImages": 1,
    "paragraphs": [
      { "ref": "s0.p0", "runs": [{ "text": "Title", "charShapeRef": 0 }] },
      { "ref": "s0.p1", "runs": [{ "text": "Body text here", "charShapeRef": 1 }] }
    ],
    "tables": [...],
    "images": [...]
  }],
  "header": { ... }
}

When --offset or --limit is used, each section includes totalParagraphs, totalTables, and totalImages counts. Without pagination flags, these fields are omitted (backward compatible).

hwpilot text ... Extract text

hwpilot text <file> [ref] [--offset <n>] [--limit <n>] [--pretty]

Without a ref, returns all text concatenated. With a ref, returns text from that element only. Use --offset and --limit to paginate paragraphs.

# All text in document
hwpilot text report.hwpx

# First 10 paragraphs of text
hwpilot text report.hwpx --limit 10

# Paragraphs 10–19
hwpilot text report.hwpx --offset 10 --limit 10

# Text from one paragraph
hwpilot text report.hwpx s0.p0

# Text from a table cell
hwpilot text report.hwpx s0.t0.r0.c0

Example output:

{ "ref": "s0.p0", "text": "Title" }

{ "text": "Title\nBody text here\nMore content" }

Example output (with pagination):

{ "text": "Para10\nPara11\nPara12", "totalParagraphs": 50, "offset": 10, "count": 3 }

hwpilot find ... Search text in document

hwpilot find <file> <query> [--json]

Searches all text containers (paragraphs, table cells, text boxes) for a case-insensitive substring match. Returns matching refs with their text. Handles text split across runs.

# Find text in any container
hwpilot find document.hwpx "청구취지"

# JSON output with container type
hwpilot find document.hwpx "청구취지" --json

Default output (one match per line):

s0.p3: 청구취지
s0.tb0.p0: 청구취지 및 청구원인

JSON output:

{"matches":[{"ref":"s0.p3","text":"청구취지","container":"paragraph"},{"ref":"s0.tb0.p0","text":"청구취지 및 청구원인","container":"textBox"}]}

No matches returns empty output (exit code 0).

hwpilot edit text ... Edit text in-place

hwpilot edit text <file> <ref> <text> [--pretty]

Replaces the text at the given ref. The file is modified in-place.

hwpilot edit text report.hwpx s0.p0 "New Title"
hwpilot edit text report.hwpx s0.t0.r0.c0 "Cell value"
hwpilot edit text report.hwpx s0.tb0.p0 "Text box content"

Example output:

{ "ref": "s0.p0", "text": "New Title", "success": true }

hwpilot edit format ... Edit character formatting

hwpilot edit format <file> <ref> [options] [--pretty]

Options:

Flag	Effect
--bold	Apply bold
--no-bold	Remove bold
--italic	Apply italic
--no-italic	Remove italic
--underline	Apply underline
--no-underline	Remove underline
--font <name>	Set font name
--size <pt>	Set font size in points
--color <hex>	Set text color (e.g. #FF0000)
--start <n>	Start character offset for inline formatting (requires --end)
--end <n>	End character offset for inline formatting (requires --start)

hwpilot edit format report.hwpx s0.p0 --bold --size 16 --font "맑은 고딕"
hwpilot edit format report.hwpx s0.p1 --italic --color "#0000FF"

# Inline formatting: bold only characters 0–4
hwpilot edit format report.hwpx s0.p0 --bold --start 0 --end 5

hwpilot table read ... Read table structure

hwpilot table read <file> <ref> [--pretty]

Returns the full table structure including all rows, cells, and their text content.

hwpilot table read report.hwpx s0.t0

hwpilot table edit ... Edit table cell text

hwpilot table edit <file> <ref> <text> [--pretty]

The ref must point to a table cell (e.g. s0.t0.r0.c0).

hwpilot table edit report.hwpx s0.t0.r0.c0 "Updated cell"
hwpilot table edit report.hwpx s0.t0.r1.c2 "3,500"

hwpilot table add ... Add a new table

hwpilot table add <file> <ref> <rows> <cols> [--position <pos>] [--data <json>] [--pretty]

Adds a new table to the document at the specified ref. The ref can be a section (s0) or a paragraph (s0.p2).

Option	Effect
--position <pos>	Insertion position: before, after, or end (default: end)
--data <json>	Cell data as JSON array of arrays

# Add a 3×4 empty table at end of section 0
hwpilot table add document.hwpx s0 3 4

# Add a 2×2 table with data
hwpilot table add document.hwpx s0 2 2 --data '[["A","B"],["C","D"]]'

# Insert a table after paragraph 2
hwpilot table add document.hwpx s0.p2 3 4 --position after

hwpilot table list ... List all tables

hwpilot table list <file> [--pretty]

Returns all tables in the document with their refs, dimensions (rows × columns), and cell text preview.

hwpilot table list report.hwpx

hwpilot paragraph add ... Add a new paragraph

hwpilot paragraph add <file> <ref> <text> [options] [--pretty]

Adds a new paragraph to the document at the specified ref.

Option	Effect
--position <pos>	Insertion position: before, after, or end (default: end)
--heading <level>	Set heading level (1–7)
--style <name>	Set paragraph style by name or ID
--bold	Bold text
--italic	Italic text
--underline	Underline text
--font <name>	Font name
--size <n>	Font size in points
--color <hex>	Text color (hex)

Note: --heading and --style are mutually exclusive.

# Append paragraph at end of section
hwpilot paragraph add document.hwpx s0 "New paragraph" --position end

# Insert paragraph before s0.p2
hwpilot paragraph add document.hwpx s0.p2 "Inserted text" --position before

# Add a heading
hwpilot paragraph add document.hwpx s0 "Chapter 1" --heading 1 --bold --size 18

hwpilot image list ... List all images

hwpilot image list <file> [--pretty]

Returns all images in the document with their refs and metadata. Works on both HWP 5.0 and HWPX files.

hwpilot image list report.hwpx

hwpilot image extract ... Extract an image to file

hwpilot image extract <file> <ref> <output-path> [--pretty]

hwpilot image extract report.hwpx s0.img0 ./logo.png

hwpilot image insert ... Insert an image

hwpilot image insert <file> <image-path> [--pretty]

hwpilot image insert report.hwpx ./photo.jpg

hwpilot image replace ... Replace an existing image

hwpilot image replace <file> <ref> <image-path> [--pretty]

hwpilot image replace report.hwpx s0.img0 ./new-logo.png

hwpilot create ... Create a new document

hwpilot create <file> [--font <name>] [--size <pt>] [--pretty]

Creates a new blank document. Defaults: font "맑은 고딕", size 10pt. Use edit text to populate content afterwards.

hwpilot create new-doc.hwpx
hwpilot create report.hwpx --font "바탕" --size 12

hwpilot convert ... Convert HWP to HWPX

hwpilot convert <input.hwp> <output.hwpx> [--force] [--pretty]

Converts a legacy HWP 5.0 file to the editable HWPX format.

Refuses to overwrite an existing output file unless --force is specified.

hwpilot convert old-doc.hwp new-doc.hwpx

hwpilot validate ... Validate HWP file integrity

hwpilot validate <file> [--viewer] [--pretty]

Validates the structural integrity of an HWP file. Optionally validates using the Hancom Office HWP Viewer app (macOS only).

hwpilot validate document.hwp
hwpilot validate document.hwp --viewer

Common Patterns

1. Read a document and understand its structure

Always start with --limit to paginate. Korean government documents often have 50+ paragraphs — dumping everything wastes context. Page through progressively.

# Get first 20 paragraphs + total counts (recommended first step)
hwpilot read document.hwpx --limit 20

# Continue reading from paragraph 20
hwpilot read document.hwpx --offset 20 --limit 20

# Drill into specific elements
hwpilot read document.hwpx s0.p0
hwpilot read document.hwpx s0.t0
hwpilot read document.hwpx s0.tb0

2. Find and edit text

Use hwpilot find to locate content by ref, then hwpilot edit text to change it. This is much faster than reading paragraphs one by one.

# Search for text across all containers (paragraphs, tables, text boxes)
hwpilot find document.hwpx "청구취지"
# Output: s0.tb0.p0: 청구취지 및 청구원인

# Edit the matched ref directly
hwpilot edit text document.hwpx s0.tb0.p0 "Updated content"

3. Fill in a template (table cells)

Read the table structure first, then edit each cell.

# See the table layout
hwpilot table read document.hwpx s0.t0

# Fill in cells one by one
hwpilot table edit document.hwpx s0.t0.r0.c0 "Name"
hwpilot table edit document.hwpx s0.t0.r0.c1 "Date"
hwpilot table edit document.hwpx s0.t0.r1.c0 "Kim Minjun"
hwpilot table edit document.hwpx s0.t0.r1.c1 "2025-01-15"

4. Fill in a form template (text boxes)

Korean government templates often use text boxes instead of tables for form fields. Use find to locate them, then edit.

# Find all form fields
hwpilot find template.hwpx "" --json
# Shows all non-empty text across paragraphs, tables, and text boxes

# Read the text box structure
hwpilot read template.hwpx s0.tb0

# Fill in text box fields
hwpilot edit text template.hwpx s0.tb0.p0 "홍길동"
hwpilot edit text template.hwpx s0.tb1.p0 "2025-01-15"

5. Extract all text for analysis

Pull the full document text without specifying a ref. Use --limit for large documents.

# First 30 paragraphs
hwpilot text document.hwpx --limit 30

# All text (can be large)
hwpilot text document.hwpx
# Returns: { "text": "all document text concatenated with newlines" }

6. Edit HWP 5.0 binary files directly

HWP 5.0 files support text, table cell, and character formatting edits in-place.

hwpilot edit text document.hwp s0.p0 "Updated title"
hwpilot edit format document.hwp s0.p0 --bold --size 18
hwpilot table edit document.hwp s0.t0.r0.c0 "New cell value"

To convert HWP to HWPX (e.g. for image operations):

hwpilot convert legacy.hwp editable.hwpx

7. Create a new document with content

Create a blank document, then populate it.

hwpilot create report.hwpx --font "맑은 고딕" --size 11
hwpilot edit text report.hwpx s0.p0 "Q4 2025 Quarterly Report"
hwpilot edit format report.hwpx s0.p0 --bold --size 18

Format Support

Important: Format is detected by file content (magic bytes), NOT by file extension. A .hwp file may contain HWPX format inside. Both HWP 5.0 and HWPX support text, table, and formatting edits.

Feature	HWPX (ZIP magic 50 4B 03 04)	HWP 5.0 (CFB magic D0 CF 11 E0)
Read structure	Yes	Yes
Read text	Yes	Yes
Edit text	Yes	Yes
Edit formatting	Yes	Yes (bold, italic, underline, fontSize, color)
Table read	Yes	Yes
Table edit	Yes	Yes
Text box read	Yes	Yes
Text box edit	Yes	Yes
Find text	Yes	Yes
Image list	Yes	Yes
Image insert/replace/extract	Yes	No (convert to HWPX first)
Create new	Yes	Yes
Paragraph add	Yes	Yes
Table add	Yes	Yes

HWPX (ZIP+XML) is the modern format with full read/write support including images.

HWP 5.0 (binary CFB) supports read and write for text, table cells, character formatting, and new document creation. Image operations require HWPX — use hwpilot convert to convert.

Limitations

What's NOT supported:

• HWP 5.0 images: Image insert, replace, and extract require HWPX format. image list works on both formats. Convert with hwpilot convert.
• Password/DRM protected files: Cannot open encrypted documents.
• Macros and scripts: No macro execution or editing.
• Equations, charts, OLE objects, video: These embedded objects can't be read or modified.
• Grouped/container shapes: Only individual text boxes are supported — grouped shapes (SHAPE_COMPONENT_CONTAINER) are ignored.
• Text box formatting: Text inside text boxes can be edited, but character formatting (edit format) on text box refs is not supported.
• Paragraph-level formatting: Alignment, spacing, indentation aren't editable. Only character formatting (bold, italic, underline, font, size, color) is supported.
• Structural additions limited: Can add paragraphs (paragraph add) and tables (table add), but cannot add new rows to existing tables or new sections.

Error Handling

All errors return JSON with an error field:

{ "error": "Paragraph not found for reference: s0.p999", "context": { "ref": "s0.p999", "file": "doc.hwp" }, "hint": "Valid paragraph refs: s0.p0 through s0.p49" }

Error responses include optional context (ref, file) and hint (valid alternatives) fields.

Common errors and fixes:

Error	Cause	Fix
Unsupported file format	File content is not HWP or HWPX	Ensure file has valid HWP/HWPX content (checked by magic bytes, not extension)
Invalid reference: s0.x1	Malformed ref	Check ref format (see Reference System above)
Section N not found	Ref points beyond document	Use hwpilot read to check available sections
Paragraph N not found	Ref points beyond section	Use hwpilot read <file> s0 to see paragraph count
Table N not found	No such table	Use hwpilot read to list tables
TextBox N not found	No such text box	Use hwpilot read to list text boxes, or hwpilot find to search
Image insert/replace/extract requires HWPX format	Write image ops on HWP 5.0 file	Convert first: hwpilot convert file.hwp file.hwpx
File already exists: <path>	Convert output file already exists	Use --force flag or choose a different output path
ENOENT: no such file	File doesn't exist	Check file path