OfficeCLI: AI 에이전트가 Word, Excel, PowerPoint 문서를 다루는 명령줄 도구

9bow · 7월 24, 2026, 5:30오전

OfficeCLI 소개

Word, Excel, PowerPoint 파일을 코드로 만들거나 고치는 일은 지금까지 python-docx, openpyxl, python-pptx 같은 라이브러리를 형식마다 따로 붙여 쓰는 방식이 일반적이었습니다. 형식이 세 가지라 API도 세 벌이고, 무엇보다 AI 에이전트가 문서를 생성할 때 결과물이 실제로 어떻게 보이는지 확인할 방법이 없었습니다. 제목이 넘쳐 잘렸는지, 도형 두 개가 겹쳤는지를 에이전트는 알지 못한 채 XML 구조만 더듬으며 작업해야 했습니다.

OfficeCLI 는 이 문제를 하나의 자체 완결형 바이너리로 묶어 해결하려는 도구입니다. .NET 런타임이 바이너리 안에 내장되어 있어 별도 설치가 필요 없고, Microsoft Office 도 요구하지 않습니다. AI 에이전트는 officecli 명령 하나로 .docx / .xlsx / .pptx 를 읽고, 고치고, 처음부터 만들 수 있으며, 모든 명령은 --json 옵션으로 일관된 스키마의 구조화된 출력을 돌려줍니다. 가장 큰 차별점은 바이너리에 내장된 HTML 렌더링 엔진입니다. 문서를 HTML 이나 PNG 로 렌더링해 에이전트가 결과를 눈으로 확인하고 고치는 render → look → fix 순환을 화면이 없는 CI · Docker 환경에서도 돌릴 수 있습니다.

OfficeCLI 는 세 형식 모두에 대해 읽기 · 수정 · 생성을 지원하고, 간단한 읽기에서 시작해 필요할 때만 깊이 내려가는 3계층 구조, 자동 계산되는 350개 이상의 Excel 함수와 피벗 테이블, 템플릿 병합, 문서 덤프 같은 기능을 담고 있습니다. 개발팀은 OfficeCLI 를 "AI 에이전트를 위해 설계된 세계 최초이자 최고의 오피스 도구" 라고 소개합니다.

OfficeCLI 의 3계층 아키텍처

OfficeCLI 는 작업의 복잡도에 따라 세 개의 계층을 제공합니다. 대부분의 작업은 위쪽 계층에서 끝나고, 저수준 제어가 필요할 때만 아래로 내려가는 구조입니다.

L1 읽기(Read) : 문서 내용을 의미 단위로 보는 계층입니다. view 명령으로 텍스트, 개요(outline), 통계, 문제점(issues), HTML, 스크린샷 등 여러 형태의 뷰를 얻습니다.
L2 DOM : 요소 단위로 구조를 조작하는 계층입니다. get, query, set, add, remove, move, swap 으로 문단 · 셀 · 도형 같은 개별 요소를 다룹니다.
L3 Raw XML : XPath 로 XML 에 직접 접근하는 범용 폴백 계층입니다. raw, raw-set, add-part, validate 로 상위 계층이 다루지 못하는 부분까지 제어합니다.

각 요소는 /slide[1]/shape[2] 같은 안정적인 경로로 지정합니다. OfficeCLI 는 XPath 가 아니라 1부터 시작하는 인덱스와 요소의 로컬 이름을 쓰는 자체 문법을 사용하므로, 에이전트가 XML 네임스페이스를 이해하지 않고도 문서 안을 탐색할 수 있습니다.

OfficeCLI 의 핵심 기능

내장 렌더링 엔진

OfficeCLI 의 핵심은 처음부터 새로 만든 고정밀 HTML 렌더링 엔진입니다. 에이전트가 DOM 만 보고 추측하는 대신 렌더링된 문서를 실제로 볼 수 있게 해줍니다. 도형, 차트(추세선 · 오차 막대 · 폭포형 · 캔들스틱 · 스파크라인), 수식(OMML → LaTeX 를 KaTeX 로 렌더링), Three.js 기반 3D .glb 모델, 모프 전환, 슬라이드 줌, 도형 효과까지 다룹니다. 세 가지 모드가 있습니다.

view html : 에셋이 인라인된 단독 HTML 파일. 아무 브라우저에서나 엽니다.
view screenshot : 페이지별 PNG. 멀티모달 에이전트가 그대로 읽을 수 있습니다.
watch : 자동 새로고침 미리보기를 제공하는 로컬 HTTP 서버. add / set / remove 를 실행할 때마다 브라우저가 즉시 갱신됩니다.

officecli view deck.pptx html -o /tmp/deck.html
officecli view deck.pptx screenshot -o /tmp/deck.png  # --page 1-N 으로 여러 슬라이드
officecli watch deck.pptx                             # http://localhost:26315

수식 · 피벗 엔진

350개 이상의 Excel 함수를 쓰기 시점에 자동으로 계산합니다. =SUM(A1:A2) 를 써 넣고 get 하면 값이 이미 들어 있어, 재계산을 위해 Office 를 거칠 필요가 없습니다. FILTER / SORT / UNIQUE / LET / LAMBDA 같은 스필(spilling) 동적 배열, VLOOKUP / XLOOKUP / INDEX / MATCH, 재무 · 채권 · 통계 함수를 지원합니다. 소스 범위로부터 OOXML 피벗 테이블을 한 명령으로 만들 수도 있으며, 피벗 캐시와 정의가 파일에 함께 기록되어 Excel 이 집계가 채워진 상태로 파일을 엽니다.

officecli add sales.xlsx '/Sheet1' --type pivottable \
  --prop source='Data!A1:E10000' --prop rows='Region,Category' \
  --prop cols=Quarter --prop values='Revenue:sum,Units:avg' \
  --prop showDataAs=percentOfTotal

템플릿 병합과 문서 덤프

merge 는 .docx / .xlsx / .pptx 안의 {{key}} 자리표시자를 JSON 데이터로 치환합니다. 문단 · 표 셀 · 도형 · 머리글 · 바닥글 · 차트 제목을 가로지릅니다. 에이전트가 레이아웃을 한 번만 설계하면(비용이 큰 작업), 이후 코드가 그 템플릿을 결정적으로 N 번 채웁니다(저렴하고 토큰 비용 없음). 매 보고서를 처음부터 다시 생성하다 N 개의 레이아웃이 제각각 달라지는 실패를 피하는 방식입니다.

dump 는 기존 문서 전체나 하위 트리(문단 하나, 표 하나, 슬라이드, 워크시트 등)를 재생 가능한 배치 JSON 으로 직렬화하고, batch 가 이를 다시 재생합니다. 흉내 내고 싶은 샘플을 주면 에이전트가 원시 OOXML 대신 구조화된 명세를 읽고 수정한 뒤 재생할 수 있습니다.

officecli dump existing.docx -o blueprint.json          # 문서 전체
officecli dump existing.xlsx /Sheet1 -o sheet.json      # 워크시트 하나
officecli batch new.docx --input blueprint.json

OfficeCLI 설치 및 사용법

단일 자체 완결형 바이너리로 배포됩니다. 한 줄로 설치하거나 패키지 매니저를 쓸 수 있습니다.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

# 패키지 매니저
brew install officecli          # Homebrew (macOS / Linux)
scoop install officecli         # Scoop (Windows)
npm install -g @officecli/officecli

설치 후 프레젠테이션을 만들고 라이브 미리보기를 켜는 최소 예시는 다음과 같습니다.

officecli create deck.pptx                    # 빈 PowerPoint 생성
officecli watch deck.pptx                      # http://localhost:26315 미리보기
officecli add deck.pptx / --type slide --prop title="Hello, World!"

이후 실행하는 모든 add · set · remove 명령이 미리보기를 실시간으로 갱신합니다. 여러 단계 작업에는 문서를 메모리에 유지하는 상주(resident) 모드와, 여러 연산을 한 번에 적용하는 배치 모드가 있습니다. 배치 모드는 기본적으로 원자적으로 동작해 한 항목이 실패하면 전체 배치를 되돌립니다.

Python 이나 Node.js 에서는 프로세스를 매번 새로 띄우지 않는 얇은 상주 파이프 SDK 를 설치해 쓸 수 있습니다.

# pip install officecli-sdk
from officecli import Doc
with Doc("deck.pptx") as d:
    d.add("/", type="slide", title="Q4 Report")
    print(d.get("/slide[1]"))

OfficeCLI 의 AI 에이전트 연동

OfficeCLI 는 Model Context Protocol(MCP) 서버를 내장하고 있어, 한 명령으로 여러 도구에 등록할 수 있습니다. 이렇게 하면 모든 문서 연산이 JSON-RPC 상의 도구로 노출되어 셸 접근이 필요 없습니다.

officecli mcp claude       # Claude Code
officecli mcp cursor       # Cursor
officecli mcp vscode       # VS Code / Copilot
officecli mcp list         # 등록 상태 확인

MCP 대신 직접 연동할 수도 있습니다. 바이너리를 설치하면 OfficeCLI 가 알려진 설정 디렉토리를 확인해 Claude Code, Cursor, GitHub Copilot 같은 AI 도구를 자동으로 감지하고 스킬 파일(SKILL.md)을 설치합니다. 에이전트는 곧바로 문서를 만들고 읽고 수정할 수 있습니다. 사람이 GUI 로 쓰고 싶다면, OfficeCLI 를 내부에서 사용하는 데스크톱 앱 AionUi 를 통해 자연어로 문서를 만들 수도 있습니다.

OfficeCLI 의 라이선스

OfficeCLI 는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

OfficeCLI 공식 홈페이지

OfficeCLI 문서 사이트

OfficeCLI 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~