CLI 사용 가이드
@ohah/hwpjs는 명령줄 인터페이스(CLI)를 제공하여 HWP 파일을 변환하고 처리할 수 있습니다.
설치
전역 설치
npm install -g @ohah/hwpjs설치 후 hwpjs 명령어를 어디서나 사용할 수 있습니다.
npx 사용 (전역 설치 없이)
npx @ohah/hwpjs <command>기본 사용법
도움말 보기
hwpjs --help특정 명령어의 도움말을 보려면:
hwpjs to-json --help
hwpjs to-markdown --help명령어
to-json - JSON 변환
HWP 파일을 JSON 형식으로 변환합니다.
# stdout으로 출력
hwpjs to-json document.hwp
# 파일로 저장
hwpjs to-json document.hwp -o output.json
# Pretty print
hwpjs to-json document.hwp -o output.json --pretty옵션:
-o, --output <file>: 출력 파일 경로 (기본값: stdout)--pretty: JSON을 포맷팅하여 출력
to-markdown - Markdown 변환
HWP 파일을 Markdown 형식으로 변환합니다.
# 기본 변환
hwpjs to-markdown document.hwp -o output.md
# 이미지 포함 (base64)
hwpjs to-markdown document.hwp -o output.md --include-images
# HTML 태그 사용
hwpjs to-markdown document.hwp -o output.md --use-html
# 버전 정보 포함
hwpjs to-markdown document.hwp -o output.md --include-version
# 페이지 정보 포함
hwpjs to-markdown document.hwp -o output.md --include-page-info옵션:
-o, --output <file>: 출력 파일 경로 (기본값: stdout)--include-images: 이미지를 base64 데이터 URI로 포함--use-html: HTML 태그 사용 (테이블 등 개행 불가 영역에<br>사용)--include-version: 버전 정보 포함--include-page-info: 페이지 정보 포함
info - 파일 정보
HWP 파일의 기본 정보를 확인합니다.
# 기본 정보 출력
hwpjs info document.hwp
# JSON 형식으로 출력
hwpjs info document.hwp --json출력 정보:
- 버전 (Version)
- 압축 여부 (Compressed)
- 암호화 여부 (Encrypted)
- 이미지 개수 (Images)
옵션:
--json: JSON 형식으로 출력
extract-images - 이미지 추출
HWP 파일에서 이미지를 추출합니다.
# 모든 이미지 추출
hwpjs extract-images document.hwp -o ./images
# 특정 형식만 추출
hwpjs extract-images document.hwp -o ./images --format jpg
hwpjs extract-images document.hwp -o ./images --format png옵션:
-o, --output-dir <dir>: 출력 디렉토리 (기본값: ./images)--format <format>: 이미지 형식 필터 (jpg,png,bmp,all) (기본값:all)
출력:
- 각 이미지는
image-{index}.{format}형식으로 저장됩니다. - 예:
image-0.jpg,image-1.png
batch - 배치 변환
디렉토리 내의 모든 HWP 파일을 일괄 변환합니다.
# JSON 형식으로 변환
hwpjs batch ./documents -o ./output --format json
# Markdown 형식으로 변환
hwpjs batch ./documents -o ./output --format markdown
# 재귀적으로 하위 디렉토리 포함
hwpjs batch ./documents -o ./output --format json --recursive
# Pretty print JSON
hwpjs batch ./documents -o ./output --format json --pretty
# Markdown에 이미지 포함
hwpjs batch ./documents -o ./output --format markdown --include-images옵션:
-o, --output-dir <dir>: 출력 디렉토리 (기본값: ./output)--format <format>: 출력 형식 (json,markdown) (기본값:json)-r, --recursive: 하위 디렉토리 포함--pretty: JSON 포맷팅 (json 형식만)--include-images: 이미지 포함 (markdown 형식만)
출력:
- 각 HWP 파일은 동일한 이름으로 변환된 파일이 생성됩니다.
- 예:
document.hwp→document.json또는document.md
사용 예제
예제 1: 단일 파일 변환
# HWP 파일을 JSON으로 변환
hwpjs to-json report.hwp -o report.json --pretty
# HWP 파일을 Markdown으로 변환 (이미지 포함)
hwpjs to-markdown report.hwp -o report.md --include-images예제 2: 여러 파일 일괄 처리
# documents 폴더의 모든 HWP 파일을 JSON으로 변환
hwpjs batch ./documents -o ./output --format json --recursive
# 변환된 파일 확인
ls ./output예제 3: 이미지 추출
# HWP 파일에서 모든 이미지 추출
hwpjs extract-images presentation.hwp -o ./images
# JPG 이미지만 추출
hwpjs extract-images presentation.hwp -o ./images --format jpg예제 4: 파일 정보 확인
# 파일 정보 확인
hwpjs info document.hwp
# JSON 형식으로 정보 확인 (스크립트에서 사용)
hwpjs info document.hwp --json | jq스크립트에서 사용
CLI를 스크립트에서 사용할 수도 있습니다:
#!/bin/bash
# 모든 HWP 파일을 JSON으로 변환
for file in *.hwp; do
hwpjs to-json "$file" -o "${file%.hwp}.json" --pretty
done// Node.js 스크립트
const { execSync } = require('child_process');
// HWP 파일 정보 가져오기
const info = JSON.parse(
execSync('hwpjs info document.hwp --json', { encoding: 'utf-8' })
);
console.log(`Version: ${info.version}`);
console.log(`Images: ${info.imageCount}`);문제 해결
명령어를 찾을 수 없음
전역 설치가 되어 있지 않은 경우:
# 전역 설치
npm install -g @ohah/hwpjs
# 또는 npx 사용
npx @ohah/hwpjs <command>참고사항
- CLI는 Node.js 환경에서만 작동합니다.
- 모든 명령어는
--help옵션으로 상세한 도움말을 볼 수 있습니다. - 출력 파일이 이미 존재하는 경우 덮어씌워집니다.
- 배치 변환 시 오류가 발생한 파일은 스킵되고 계속 진행됩니다.