OpenHwp Automation

https://github.com/zarathucorp/openhwpsdk
Admin
OpenHwp Automation provides Windows-first C# automation and CLI tooling for working with Hancom...
Tokens:50,612
Snippets:328
Trust Score:9.2
Update:1 day ago
Show doc for...
Tokens:
Raw
### Preview documentation locally with pip and mkdocs

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/README.md

Install documentation dependencies and start the local MkDocs server. Run these commands from the project root.

```bat
python -m pip install -r requirements-docs.txt
mkdocs serve
```

--------------------------------

### Create scratch output directory

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/README.md

Creates the C:\temp directory used as the scratch output location for the quick start commands. Run this before building or using the CLI.

```bat
mkdir C:\temp
```

--------------------------------

### Cell write example

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

XML example for writing text to a table cell, with optional image insertion and clearCell flag.

```xml
<cell id="table-003-r001-c001" tableIndex="3" row="1" col="1" merged="false">
  <currentText>Existing cell text</currentText>
  <writeText>Replacement cell text</writeText>
  <writeImage path="" width="200" height="200" clearCell="true" />
</cell>
```

--------------------------------

### Cell image insertion example

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

XML example for inserting an image into a cell, using a path relative to the map XML.

```xml
<writeImage path="sample_insert.png" width="40" height="20" clearCell="true" />
```

--------------------------------

### List, check, get, and set fields

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Commands to list raw fields, check if a field exists, get a field value, and set a field value with visible mode. The field-set command writes to an output file.

```powershell
& $cli field-list-raw '<form.hwp>'
& $cli field-exists '<form.hwp>' 'FIELD_NAME'
& $cli field-get '<form.hwp>' 'FIELD_NAME'
& $cli --visible field-set '<form.hwpx>' 'FIELD_NAME' 'updated text' 'test\out\form-out.hwpx'
```

--------------------------------

### Paragraph anchor text replacement example

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

XML example for replacing paragraph anchor text, with replaceAnchorText attribute.

```xml
<anchor id="anchor-0001" partPath="Contents/section0.xml" partRole="bodySection" paragraphIndex="1" occurrence="0">
  <currentText>Existing paragraph text</currentText>
  <writeText replaceAnchorText="true">Replacement paragraph text</writeText>
</anchor>
```

--------------------------------

### Create a simple HWPX document

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/README.md

Creates a new HWPX document at C:\temp\hello.hwpx with the text 'Hello from OpenHwp'. Requires the CLI to be built first.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe new-text C:\temp\hello.hwpx "Hello from OpenHwp"
```

--------------------------------

### Fill submission template with R&D startup profile

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

Use this command to fill an HWPX template from a Markdown source using the r-and-d-startup-2026 profile. It renders Markdown tables as HWPX table objects by default and queues image lines for package-level insertion. Use --image-mode com only when local HWP COM is healthy; use --image-mode none for text/table-only staging.

```powershell
& $cli fill-submission-template '<template.hwpx>' '<source.md>' 'test\out\submission_filled.hwpx' --profile r-and-d-startup-2026 --asset-root '<image-root>' --image-mode package --report 'test\out\submission_filled_report.md'
```

--------------------------------

### Build Release x86

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

Builds the CLI in Release configuration. Run this first before using the CLI.

```powershell
Set-Location -LiteralPath 'C:\Users\ZARATHU11\codex\openhwpsdk'
.\build.cmd Release
```

--------------------------------

### Run COM health check

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/README.md

Runs a COM health check with the --visible flag before editor-backed workflows. Requires Windows with Hancom HWP/Hanword installed.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible diagnose-com
```

--------------------------------

### Build the CLI

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/README.md

Builds the OpenHwp.Automation.Cli in Release configuration using the build.cmd script. Requires MSBuild or Visual Studio Build Tools.

```bat
build.cmd Release
```

--------------------------------

### Create a new HWPX document

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/getting-started.md

Creates a simple HWPX document at the specified path with the given text content.

```powershell
& $cli new-text C:\temp\hello.hwpx "Hello from OpenHwp"
```

--------------------------------

### Build static site

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/documentation-site.md

Build the static site into the `site/` directory, which is ignored by Git.

```powershell
mkdocs build --clean --site-dir site
```

--------------------------------

### Run list-controls, probe-copy-from-doc, and copy-from-doc commands

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

These three commands are shown together as the primary workflow for inspecting controls and copying content from a reference document into a target. Use probe-copy-from-doc before mutation. Source selectors support all, paragraph-to-end:<text>, table:<index>, image:<index>, and control:<ctrlId>:<index>. image:<index> maps to gso controls; use the typeIndex column from list-controls, not the global index column. Target selectors can use doc-end, anchor:<text>, cell:<table,rowMove,colMove>, or control:<ctrlId>:<index>. After a copy, run scan-hwpx-features, validate-layout, and PDF export when visual placement matters.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible list-controls "<reference.hwpx>" "C:\temp\openhwpsdk-out\reference_controls.md"
```

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible probe-copy-from-doc "<reference.hwpx>" "<target.hwpx>" --source image:0 --target doc-end --report "C:\temp\openhwpsdk-out\copy_probe.md"
```

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible copy-from-doc "<reference.hwpx>" "<target.hwpx>" "C:\temp\openhwpsdk-out\copy_from_doc.hwpx" --source image:0 --target doc-end --report "C:\temp\openhwpsdk-out\copy_from_doc.md"
```

--------------------------------

### Build and locate the CLI executable

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Sets the working directory to the project path, runs the build script with the Release configuration, and constructs the path to the CLI executable. The project targets .NET Framework 4.0 and x86 because Hancom HWP automation is COM-based.

```powershell
Set-Location -LiteralPath 'C:\Users\ZARATHU11\codex\openhwpsdk'
.\build.cmd Release
$cli = Join-Path (Get-Location) 'src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe'
```

--------------------------------

### Fill an existing HWPX table without recreating it

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Creates a new HWPX file by filling an existing table in the template. The command uses table-create-package with specified rows, columns, and text content.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe table-create-package "<template.hwpx>" "C:\temp\openhwpsdk-out\new_table.hwpx" --rows 2 --cols 3 --text "Header A|Header B|Header C;Value 1|Value 2|Value 3" --report "C:\temp\openhwpsdk-out\new_table_report.md"
```

--------------------------------

### Fill submission template with profile

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/cli-reference.md

Fills a submission template with content from a Markdown file, using the r-and-d-startup-2026 profile. Use --markdown-table-mode text only when preserving original HWPX table count matters more than table semantics. Use --image-mode com only when local HWP COM is healthy and editor-backed image insertion is required.

```powershell
& $cli fill-submission-template C:\temp\template.hwpx C:\temp\source.md C:\temp\submission-filled.hwpx --profile r-and-d-startup-2026 --asset-root C:\temp --image-mode package --report C:\temp\submission-filled-report.md
```

--------------------------------

### Run scan-hwpx-features, list-header-footer, set-header-footer-text, add-header-footer-reference, add-header-footer-text, page-number-set, and list-fields commands

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

These commands scan HWPX feature coverage, list header/footer bodies, set header/footer text, add header/footer references, add header/footer text, set page numbers, and list fields. The feature scan report separates corpus evidence from implementation support and includes aggregate counts, authoring coverage, detailed feature groups, missing corpus signals, per-file totals, and inventory tables for header/footer bodies and references, field/form objects, bookmarks, captions, hyperlinks, cross references, TOC/index markers, page/auto numbers, footnotes, endnotes, memos, and comments.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe scan-hwpx-features "C:\temp\hwpx-samples" "C:\temp\hwpx_feature_scan.md"
```

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe list-header-footer "C:\temp\template.hwpx" "C:\temp\header_footer_inventory.md"
```

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe set-header-footer-text "C:\temp\template.hwpx" "C:\temp\header_footer_text_write.hwpx" --kind header --section section0 --anchor "Header fixture" --text "Updated Header Fixture" --report "C:\temp\header_footer_text_write.md"
```

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe add-header-footer-reference "C:\temp\template.hwpx" "C:\temp\header_footer_reference.hwpx" --kind footer --section section0 --id-ref footer-ref --apply-page-type ODD --report "C:\temp\header_footer_reference.md"
```

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe add-header-footer-text "C:\temp\template.hwpx" "C:\temp\header_footer_text.hwpx" --kind footer --section section0 --id-ref footer-odd --apply-page-type ODD --text "Odd footer" --report "C:\temp\header_footer_text.md"
```

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible page-number-set "<template.hwpx>" "C:\temp\page_numbered.hwpx" --draw-pos 5 --side-char "-" --report "C:\temp\page_numbered.md"
```

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible list-fields "<template.hwpx>" "C:\temp\field_inventory.md" --com
```

--------------------------------

### Project directory layout

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/README.md

Shows the top-level structure of the repository, including source folders, docs, skills, and configuration files.

```text
.
|-- src/
|   |-- OpenHwp.Automation/        C# COM automation wrapper
|   `-- OpenHwp.Automation.Cli/    Windows CLI and HWPX package utilities
|-- docs/                          GitHub Pages documentation source
|-- skills/                        Codex skill packaging for local workflows
|-- build.cmd                      Windows build entrypoint
`-- mkdocs.yml                     Documentation site configuration
```

--------------------------------

### Basic CLI commands

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/cli-reference.md

Shows the core CLI commands for version, creating text documents, copying/saving, reading document info, reading text, reading pages, and exporting to PDF. The --visible flag is used for export-pdf to enable the desktop editor.

```powershell
$cli = "src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe"
& $cli version
& $cli new-text C:\temp\hello.hwpx "Hello from OpenHwp"
& $cli copy-save C:\temp\in.hwpx C:\temp\out.hwpx
& $cli doc-info C:\temp\in.hwp
& $cli read-text C:\temp\in.hwp
& $cli read-page C:\temp\in.hwp 1
& $cli --visible export-pdf C:\temp\in.hwpx C:\temp\out.pdf
```

--------------------------------

### GitHub Actions workflow file path

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/documentation-site.md

Path to the workflow file that builds and deploys the documentation site.

```text
.github/workflows/docs.yml
```

--------------------------------

### Probe and copy rich content from reference document

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

Use these commands to probe and copy rich content (images, tables, text) from a reference HWP/HWPX into a target document. The probe command checks compatibility before the actual copy. copy-from-doc supports sources like all, paragraph-to-end:<text>, table:<index>, image:<index>, and control:<ctrlId>:<index>; targets can be doc-end, anchor:<text>, cell:<table,rowMove,colMove>, or control:<ctrlId>:<index>.

```powershell
& $cli list-pictures '<reference.hwpx>' 'test\out\reference_pictures.md'
```

```powershell
& $cli --visible list-controls '<reference.hwpx>' 'test\out\reference_controls.md'
```

```powershell
& $cli --visible probe-copy-from-doc '<reference.hwpx>' '<target.hwpx>' --source image:0 --target doc-end --report 'test\out\copy_probe.md'
```

```powershell
& $cli --visible copy-from-doc '<reference.hwpx>' '<target.hwpx>' 'test\out\copy_from_doc.hwpx' --source image:0 --target doc-end --report 'test\out\copy_from_doc.md'
```

--------------------------------

### Check the executable version

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/README.md

Displays the version of the built OpenHwp.Automation.Cli executable. The path points to the Release output.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe version
```

--------------------------------

### PowerShell commands for listing pictures, controls, probing copy, and copying from document

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/cli-reference.md

Run probe-copy-from-doc before mutation. Validate copied output with feature scans, layout checks, and visual/PDF review when placement matters.

```powershell
& $cli list-pictures C:\temp\reference.hwpx C:\temp\reference-pictures.md
& $cli --visible list-controls C:\temp\reference.hwpx C:\temp\reference-controls.md
& $cli --visible probe-copy-from-doc C:\temp\reference.hwpx C:\temp\target.hwpx --source image:0 --target doc-end --report C:\temp\copy-probe.md
& $cli --visible copy-from-doc C:\temp\reference.hwpx C:\temp\target.hwpx C:\temp\copied.hwpx --source image:0 --target doc-end --report C:\temp\copy-report.md
```

--------------------------------

### Fill submission template with profile command

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Uses the dedicated profile command for the current submission form instead of hand-editing every map entry. The profile queues supported Markdown image lines as text anchors, then inserts images with package-level BinData/hp:pic updates by default. Use --image-mode com only when the local HWP COM session is known to be healthy. Body Markdown tables default to rendered HWPX table objects; use --markdown-table-mode text only when preserving the original table count matters more than table semantics.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe fill-submission-template "<template.hwpx>" "<source.md>" "C:\temp\openhwpsdk-out\submission_filled.hwpx" --profile r-and-d-startup-2026 --asset-root "<image-root>" --image-mode package --report "C:\temp\openhwpsdk-out\submission_filled_report.md"
```

--------------------------------

### table-create-package

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Creates a new simple table by cloning defaults from an existing unmerged top-level table. Requires a safe reference table and validates inserted text and layout.

```APIDOC
## table-create-package

### Description
Creates a new simple table by cloning stable defaults from an existing unmerged top-level table in the source HWPX. Fails if no safe reference table exists.

### Method
Command

### Endpoint
`table-create-package`

### Parameters
#### Options
- `--after-anchor` - Optional - Targets only top-level body paragraphs for insertion.
- `--rows` - Required - Number of rows for the new table.
- `--cols` - Required - Number of columns for the new table.
- Text input - Required - Content for inserted cells; ignored or missing cells are reported if the source matrix does not match `--rows` x `--cols`.

### Validation
- Use content requirements for inserted text.
- Use `validate-layout` to confirm the expected table count increase does not disturb existing tables.

```

--------------------------------

### List Markdown tables

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Lists Markdown tables from a source file using the CLI.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe markdown-table-list "<source.md>"
```

--------------------------------

### Set default repo root

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

Shows the default repository root on this machine. Replace with the current repo path if the checkout differs.

```powershell
C:\Users\ZARATHU11\codex\openhwpsdk
```

--------------------------------

### Documentation directory structure

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/documentation-site.md

The expected layout of the `docs/` directory with Markdown files and an assets folder.

```text
docs/
|-- index.md
|-- getting-started.md
|-- cli-reference.md
|-- image-replacement.md
|-- markdown-hwpx-validation-workflow.md
|-- hwp-authoring-feature-roadmap.md
|-- submission-hwpx-code-issues.md
|-- table-edit-improvement-plan.md
`-- assets/
```

--------------------------------

### Replace image control in HWPX package

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/cli-reference.md

Lists pictures in a template and replaces the image binary of a specific control while preserving placement, wrapping, margins, crop, z-order, and anchor behavior. Requires a template HWPX file and a new image file.

```powershell
& $cli list-pictures C:\temp\template.hwpx C:\temp\picture-inventory.md
& $cli replace-image-control C:\temp\template.hwpx C:\temp\replaced.hwpx --target control:gso:0 --image C:\temp\new-image.png --report C:\temp\replace-image-report.md
```

--------------------------------

### Apply filled form map in package mode (COM-free)

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Applies the filled map without COM, preserving original HWPX package entries, applying XML text changes, embedding writeImage paths as package-level BinData/hp:pic objects, and running layout validation after writing. The layout report is written as *.layout.md next to the apply report.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe apply-form-map --package "<template.hwpx>" "C:\temp\openhwpsdk-out\template_form_map_filled.xml" "C:\temp\openhwpsdk-out\template_form_map_package_applied.hwpx" --report "C:\temp\openhwpsdk-out\template_form_map_package_apply.md"
```

--------------------------------

### Local preview URL

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/documentation-site.md

The default URL where MkDocs serves the site locally.

```text
http://127.0.0.1:8000/
```

--------------------------------

### List Markdown tables and fill existing table cells

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

First inspect Markdown tables with markdown-table-list, then fill existing cells with fill-markdown-table. Use row/column table writes carefully around merged or irregular tables; prefer map/probe evidence before claiming the cell target is safe.

```powershell
& $cli markdown-table-list '<source.md>'
```

```powershell
& $cli --visible fill-markdown-table '<template.hwpx>' '<source.md>' 'test\out\table-out.hwpx' 8 3 1 0 1 2 5
```

--------------------------------

### HWPX Feature and Header/Footer Management Commands

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

Batch of PowerShell commands for scanning HWPX features, listing pictures, managing headers/footers, setting page numbers, and listing fields. Use these for feature coverage analysis and header/footer operations. Verify header/footer changes with list-header-footer, validate-content, and validate-layout.

```powershell
& $cli scan-hwpx-features 'C:\temp\hwpx-samples' 'C:\temp\hwpx_feature_scan.md'
& $cli list-pictures 'C:\temp\template.hwpx' 'C:\temp\picture_inventory.md'
& $cli list-header-footer 'C:\temp\template.hwpx' 'C:\temp\header_footer_inventory.md'
& $cli set-header-footer-text 'C:\temp\template.hwpx' 'C:\temp\header_footer_text_write.hwpx' --kind header --section section0 --anchor 'Header fixture' --text 'Updated Header Fixture' --report 'C:\temp\header_footer_text_write.md'
& $cli add-header-footer-reference 'C:\temp\template.hwpx' 'C:\temp\header_footer_reference.hwpx' --kind footer --section section0 --id-ref footer-ref --apply-page-type ODD --report 'C:\temp\header_footer_reference.md'
& $cli add-header-footer-text 'C:\temp\template.hwpx' 'C:\temp\header_footer_text.hwpx' --kind footer --section section0 --id-ref footer-odd --apply-page-type ODD --text 'Odd footer' --report 'C:\temp\header_footer_text.md'
& $cli --visible page-number-set '<template.hwpx>' 'C:\temp\page_numbered.hwpx' --draw-pos 5 --side-char '-' --report 'C:\temp\page_numbered.md'
& $cli --visible list-fields '<template.hwpx>' 'C:\temp\field_inventory.md' --com
```

--------------------------------

### List Pictures with list-pictures

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/image-replacement.md

Generates a picture inventory report from a template HWPX file. The report includes the package-order graphical-object index, image reference, resolved BinData path, pixel size, SHA256, and key placement/wrap properties.

```powershell
$cli = "src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe"
& $cli list-pictures C:\temp\template.hwpx C:\temp\picture-inventory.md
```

--------------------------------

### Apply form map via HWP automation

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Applies the form map through HWP automation when editor-backed behavior matters. The --visible flag shows HWP, and --report generates a report file.

```powershell
& $cli --visible apply-form-map '<template.hwpx>' 'test\out\template_form_map_filled.xml' 'test\out\template_form_map_applied.hwpx' --report 'test\out\template_form_map_apply.md'
```

--------------------------------

### Copy from a reference document through HWP clipboard

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Copies content from a reference document to a target using HWP's editor-backed clipboard path. Supports source selectors like all, paragraph-to-end:<text>, table:<index>, image:<index>, control:<ctrlId>:<index>. For image/gso sources, post-verifies the saved package and reports post_verify=verified|failed|skipped. Add --strict-cleanup to fail on newly remaining HWP processes.

```powershell
& $cli --visible copy-from-doc '<reference.hwpx>' '<target.hwpx>' 'test\out\copy_from_doc.hwpx' --source image:0 --target doc-end --report 'test\out\copy_from_doc.md'
```

--------------------------------

### Form Map Workflow commands

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/cli-reference.md

Extracts a form map from a template, probes it, and applies it to fill a document. Use package mode (--package) when COM-free text, image, press-field, or checkbox writes are enough; use HWP-backed mode when editor behavior is required.

```powershell
& $cli extract-form-map C:\temp\template.hwpx C:\temp\template-form-map.xml
& $cli --visible probe-form-map C:\temp\template.hwpx C:\temp\template-form-map.xml C:\temp\template-probe.md
& $cli --visible apply-form-map C:\temp\template.hwpx C:\temp\template-form-map.xml C:\temp\filled.hwpx --report C:\temp\filled-apply.md
& $cli apply-form-map --package C:\temp\template.hwpx C:\temp\template-form-map.xml C:\temp\filled-package.hwpx --report C:\temp\filled-package-apply.md
```

--------------------------------

### Export PDFs for visual inspection

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Batch commands to export HWPX templates to PDF using the OpenHwp.Automation.Cli executable with the --visible flag. The first command exports a template file, the second exports a specific output file.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible export-pdf "<template.hwpx>" "C:\temp\openhwpsdk-out\template_original.pdf"
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible export-pdf "C:\temp\openhwpsdk-out\cell_fill_education_2rows.hwpx" "C:\temp\openhwpsdk-out\cell_fill_education_2rows.pdf"
```

--------------------------------

### GitHub Pages source configuration

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/documentation-site.md

Repository settings path to configure Pages to use GitHub Actions as the source.

```text
Settings > Pages > Build and deployment > Source: GitHub Actions
```

--------------------------------

### Apply form map in package mode

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Applies the form map using package mode for COM-free text writes and package-level image embedding. Package anchor writes are applied from later paragraphs toward earlier paragraphs to reduce repeated-anchor drift.

```powershell
& $cli apply-form-map --package '<template.hwpx>' 'test\out\template_form_map_filled.xml' 'test\out\template_form_map_package.hwpx' --report 'test\out\template_form_map_package_apply.md'
```

--------------------------------

### Validate layout with allow-table-row-change

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Command-line invocation of OpenHwp.Automation.Cli.exe to validate layout, allowing intentional row expansion by table index 10.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe validate-layout "<template.hwpx>" "C:\temp\openhwpsdk-out\submission_filled.hwpx" "C:\temp\openhwpsdk-out\submission_filled_layout.md" --allow-table-row-change 10
```

--------------------------------

### Replace Image Control in HWPX

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

COM-free command to replace an image control while preserving its properties. Uses the package-order index from list-pictures. Fails on shared image references or shared resolved BinData paths. Writes a sibling validate-layout report when --report is provided.

```powershell
& $cli replace-image-control '<template.hwpx>' 'test\out\image_replaced.hwpx' --target control:gso:0 --image '<new-image.png>' --report 'test\out\image_replace_report.md'
```

--------------------------------

### Fill a Markdown table into an HWPX table

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Fills a Markdown table into an HWPX table using the --visible flag and fill-markdown-table command with positional arguments for table index, row, column, and dimensions.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe --visible fill-markdown-table "<template.hwpx>" "<source.md>" "C:\temp\openhwpsdk-out\cell_fill_education_2rows.hwpx" 8 3 1 0 1 2 5
```

--------------------------------

### Validate HWPX layout and content with OpenHWP CLI

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

Run validation commands to check layout and content of generated HWPX files. Use --allow-table-row-change to tolerate table row changes, and --require to specify required text. Export PDF for visual inspection. Accept only when reports are clean or warnings reviewed.

```powershell
& $cli validate-layout '<template.hwpx>' '<candidate.hwpx>' 'test\out\layout_report.md'
& $cli validate-layout '<template.hwpx>' '<candidate.hwpx>' 'test\out\layout_report.md' --allow-table-row-change 10
& $cli validate-content '<candidate.hwpx>' 'test\out\content_report.md' --require 'required text'
& $cli --visible export-pdf '<candidate.hwpx>' 'test\out\candidate.pdf'
```

--------------------------------

### Read document info, text, page, and export PDF

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Commands to retrieve document info, extract text, extract a specific page, and export to PDF. Prefer file output for Korean text because terminal rendering can be misleading.

```powershell
& $cli doc-info '<input.hwp>'
& $cli read-text '<input.hwp>' 'test\out\input_text.txt'
& $cli read-page '<input.hwp>' 1 'test\out\page_001.txt'
& $cli --visible export-pdf '<input.hwpx>' 'test\out\input.pdf'
```

--------------------------------

### Run COM diagnosis with optional input file

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Runs the diagnose-com command with the --visible flag. Optionally pass an input HWPX file to diagnose. Useful for checking COM automation issues.

```powershell
& $cli --visible diagnose-com
& $cli --visible diagnose-com '<input.hwpx>'
```

--------------------------------

### Set CLI path and check version in PowerShell

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/getting-started.md

Defines a PowerShell variable pointing to the built CLI executable and runs the version command. Useful for shorter commands in PowerShell.

```powershell
$cli = "src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe"
& $cli version
```

--------------------------------

### list-fields

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/SKILL.md

Lists fields and form elements, optionally merging with HWP COM field-list output.

```APIDOC
## list-fields

### Description
Lists fields and form elements, optionally merging with HWP COM field-list output.

### Method
CLI Command

### Endpoint
`& $cli --visible list-fields <inputPath> <reportPath> --com`

### Parameters
- **--visible** (flag) - Optional - Makes the COM automation visible.
- **inputPath** (string) - Required - Path to the input HWPX file.
- **reportPath** (string) - Required - Path where the report will be written.
- **--com** (flag) - Optional - Merges package field/form rows with HWP COM field-list output.

### Request Example
```powershell
& $cli --visible list-fields '<template.hwpx>' 'C:\temp\field_inventory.md' --com
```

### Response
#### Success Response
- Report file written to the specified path.

#### Response Example
Report includes package field/form rows and, when `--com` is used, HWP COM field-list output.
```

--------------------------------

### Run COM diagnosis with timeout

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Runs diagnose-com with a clear timeout of 120000 ms while visible. Use this if HWP automation hangs.

```powershell
& $cli --visible --com-timeout-ms 120000 diagnose-com '<input.hwpx>'
```

--------------------------------

### list-controls

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Lists controls in a reference HWPX document. This command is used to inspect the document before copying content.

```APIDOC
## list-controls

### Description
Lists controls in a reference HWPX document.

### Method
CLI Command

### Endpoint
`& $cli --visible list-controls '<reference.hwpx>' 'test\out\reference_controls.md'`

### Parameters
#### Positional Parameters
- **reference.hwpx** (string) - Required - Path to the reference HWPX file.
- **output.md** (string) - Required - Path to the output markdown file.

### Request Example
```powershell
& $cli --visible list-controls 'reference.hwpx' 'output.md'
```

### Response
#### Success Response
- Writes a markdown report of controls to the output file.

#### Response Example
```
Report written to output.md
```
```

--------------------------------

### Fill an existing HWP table from a Markdown table

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Fills an existing HWP table without recreating it. Parameters include markdownTableIndex, hwpTableIndex, and optional startRow, startCol, skipMarkdownRows, maxRows, maxCols. Uses --visible to show the HWP window.

```powershell
& $cli --visible fill-markdown-table '<template.hwpx>' '<source.md>' 'test\out\table-out.hwpx' <markdownTableIndex> <hwpTableIndex> [startRow] [startCol] [skipMarkdownRows] [maxRows] [maxCols]
```

--------------------------------

### copy-from-doc

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/skills/openhwpsdk-windows-cli/references/windows-cli-recipes.md

Copies content from a reference document to a target document using HWP's editor-backed clipboard path. This command supports various source and target selectors and can post-verify the saved package.

```APIDOC
## copy-from-doc

### Description
Copies content from a reference document to a target document using HWP's editor-backed clipboard path.

### Method
CLI Command

### Endpoint
`& $cli --visible copy-from-doc '<reference.hwpx>' '<target.hwpx>' 'test\out\copy_from_doc.hwpx' --source image:0 --target doc-end --report 'test\out\copy_from_doc.md'`

### Parameters
#### Positional Parameters
- **reference.hwpx** (string) - Required - Path to the reference HWPX file.
- **target.hwpx** (string) - Required - Path to the target HWPX file.
- **output.hwpx** (string) - Required - Path to the output HWPX file.

#### Options
- **--source** (string) - Required - Source selector. Supported values: `all`, `paragraph-to-end:<text>`, `table:<index>`, `image:<index>`, `control:<ctrlId>:<index>`.
- **--target** (string) - Required - Target selector. Supported values: `doc-end`, `anchor:<text>`, `cell:<table,rowMove,colMove>`, `control:<ctrlId>:<index>`.
- **--report** (string) - Required - Path to the report file.
- **--strict-cleanup** (flag) - Optional - When present, makes copy/probe fail if a new HWP process remains, without terminating user-owned HWP windows.

### Request Example
```powershell
& $cli --visible copy-from-doc 'reference.hwpx' 'target.hwpx' 'output.hwpx' --source image:0 --target doc-end --report 'report.md'
```

### Response
#### Success Response
- Creates the output HWPX file with the copied content.
- The report includes a `post_verify` field with values `verified`, `failed`, or `skipped`.

#### Response Example
```
Output file written to output.hwpx
Report written to report.md
```
```

--------------------------------

### Add rows to an HWPX table

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Adds rows to an existing table in the template. The command uses table-row-package with --table-index, --action add, --row, --count, and --text.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe table-row-package "<template.hwpx>" "C:\temp\openhwpsdk-out\row_added.hwpx" --table-index 4 --action add --row 1 --count 2 --text "R1C1|R1C2|R1C3|R1C4;R2C1|R2C2|R2C3|R2C4" --report "C:\temp\openhwpsdk-out\row_added_report.md"
```

--------------------------------

### Export HWPX to PDF via HWP COM

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/getting-started.md

Exports the document to PDF using HWP COM. The --visible flag makes the HWP session visible, which is recommended when debugging.

```powershell
& $cli --visible export-pdf C:\temp\hello.hwpx C:\temp\hello.pdf
```

--------------------------------

### Run validate-layout command

Source: https://github.com/zarathucorp/openhwpsdk/blob/main/docs/markdown-hwpx-validation-workflow.md

Runs structural layout validation on a template and an output file, producing a layout report. Use this to verify visual placement after copy operations.

```bat
src\OpenHwp.Automation.Cli\bin\Release\OpenHwp.Automation.Cli.exe validate-layout "<template.hwpx>" "C:\temp\openhwpsdk-out\cell_fill_education_2rows.hwpx" "C:\temp\openhwpsdk-out\cell_fill_education_2rows_layout_report.md"
```
Tokens:
Raw