[DevOps] OfficeCLI 소개 및 사용 방법

개요

OfficeCLI는 Word, Excel, PowerPoint 파일을 터미널에서 읽고 수정하고 생성하는 오픈소스 도구다. 기존에는 python-docx, openpyxl, python-pptx처럼 형식마다 라이브러리를 나누거나 Microsoft Office 자동화 환경을 따로 준비해야 했다.

 

OfficeCLI는 .docx, .xlsx, .pptx에 같은 명령 체계를 사용한다.

AI 에이전트가 쓰기 쉽게 만든 점도 분명하다. 문서 요소를 경로로 지정하고 JSON으로 읽을 수 있다.

결과를 HTML이나 PNG로 렌더링해 화면을 확인하고 다시 고치는 흐름도 만들 수 있다.

주요 특징

OfficeCLI는 .NET 런타임을 포함한 단일 바이너리다.

Microsoft Office를 설치하지 않은 macOS, Linux, Windows에서 실행할 수 있다.

• .docx, .xlsx, .pptx 읽기·수정·생성
• /slide[1]/shape[1] 같은 경로 기반 요소 선택
• 문서 구조와 속성을 텍스트 또는 JSON으로 조회
• HTML·PNG 렌더링과 자동 갱신 미리보기인 watch
• JSON 데이터로 템플릿을 채우는 merge
• 여러 변경을 묶는 batch와 resident mode

형식마다 다른 API를 익히지 않아도 된다는 점은 배치 작업에서 편하다.

CI 컨테이너에서도 Office 없이 문서를 만들고 이미지로 확인할 수 있다.

라이선스는 Apache License 2.0이다.

사용이 필요한 상황

• 데이터베이스나 API 결과를 정기 보고서로 만들 때
• 여러 문서의 문구와 스타일을 한꺼번에 바꿀 때
• AI 에이전트가 만든 문서를 렌더링해 다시 검사할 때
• CI/CD에서 문서 생성과 구조 검증을 자동화할 때
• 기존 템플릿에 고객별 데이터를 반복해서 채울 때

문서를 한두 번 만드는 작업은 GUI가 빠를 수 있다. 반복 처리나 서버 실행처럼 사람이 Office 화면을 열기 어려운 환경에 더 잘 맞는다.

설치 또는 시작 방법

macOS와 Linux에서는 Homebrew 또는 설치 스크립트를 사용할 수 있다.

Windows는 Scoop과 PowerShell 스크립트를 지원하며, npm 패키지도 제공한다.

brew install officecli
officecli --version

운영 서버나 CI에서는 원라인 설치 스크립트보다 GitHub Releases의 특정 버전을 고정해 받는 방식을 검토할 만하다.

실습

PowerPoint 파일을 만들고 브라우저에서 결과를 확인하는 예시다.

officecli create demo.pptx
officecli add demo.pptx / --type slide \
  --prop title="월간 운영 보고서" --prop background=1A1A2E
officecli add demo.pptx '/slide[1]' --type shape \
  --prop text="장애 2건, 평균 복구 18분" \
  --prop x=2cm --prop y=5cm --prop size=24 --prop color=FFFFFF

officecli view demo.pptx outline
officecli view demo.pptx html
officecli close demo.pptx

create는 빈 파일을 만들고 add는 슬라이드와 도형을 넣는다.

view로 구조와 렌더링 결과를 확인한다.

마지막 close는 메모리의 변경을 파일에 기록하고 세션을 끝낸다.

 

수정을 반복한다면 officecli watch demo.pptx를 실행해 둔다.

문서에 {{client}} 같은 자리표시자가 있으면 merge로 JSON 데이터를 넣어 복사본을 만들 수 있다.

알아야 할 사항

내장 렌더링 엔진은 Microsoft Office 자체가 아니다.

복잡한 차트, 글꼴, 애니메이션이 있는 문서는 실제 배포 대상인 PowerPoint나 Excel에서도 열어 봐야 한다.

공식 지원 목록은 .docx, .xlsx, .pptx 중심이다. 오래된 형식과 매크로 포함 형식은 별도 확인이 필요하다.

 

도구는 백그라운드에서 업데이트를 확인한다.

재현성이 필요한 CI에서는 버전을 고정하고 officecli config autoUpdate false 또는 OFFICECLI_SKIP_UPDATE=1을 검토한다.

watch는 로컬 HTTP 미리보기를 열기 때문에 공유 서버에서는 포트 노출 범위도 살펴야 한다.

OfficeCLI 보안 정책은 이 도구가 신뢰하지 않는 Office 파일을 처리할 수 있다는 점을 명시한다.

외부 파일은 격리된 컨테이너에서 처리하고 입력 크기와 실행 시간을 제한하는 편이 안전하다.

이 글의 명령은 공식 README를 기준으로 작성했다.

장점과 아쉬운 점

장점:

• 세 Office 형식에 같은 CLI와 경로 문법을 사용한다.
• Office가 없는 서버에서 생성과 렌더링을 처리할 수 있다.
• JSON 출력과 미리보기는 AI 에이전트의 수정·검사 흐름에 맞는다.

아쉬운 점:

• 복잡한 문서는 경로와 속성 문법을 익혀야 한다.
• 내장 렌더링과 Microsoft Office 화면이 같다고 단정할 수 없다.
• 운영 환경은 버전 고정과 회귀 검사가 필요하다.

정리

OfficeCLI는 Office 문서 자동화를 형식별 라이브러리 대신 하나의 CLI로 다룬다.

정기 보고서 생성, 템플릿 병합, CI 문서 검사, AI 에이전트 연동을 준비하는 개발자와 플랫폼 팀에 맞는다.

작은 템플릿 한 개로 생성, 수정, 렌더링, 실제 Office 열기까지 검증한 뒤 범위를 넓히는 편이 안전하다.

적용 전 README, 릴리스 노트, 보안 정책도 다시 확인해야 한다.

참고 자료

• OfficeCLI GitHub
• OfficeCLI 한국어 README
• OfficeCLI Releases
• OfficeCLI Security Policy
• OfficeCLI License