OfficeCLI 사용법: 설치부터 AI 에이전트 연동까지
OfficeCLI는 워드·엑셀·파워포인트를 명령줄에서 다루는 무료 오픈소스(아파치 2.0) 도구다. 공식 GitHub 저장소 기준 오피스 설치 없이 단일 바이너리로 동작하며, 설치와 기본 명령, Claude Code 연동까지 정리했다.
목차
OfficeCLI는 워드·엑셀·파워포인트 파일을 명령줄에서 만들고 읽고 고치는 무료 오픈소스 도구다. 마이크로소프트 오피스를 설치하지 않아도 되고, 파일 하나짜리 실행 바이너리로 동작한다. OfficeCLI 공식 GitHub 저장소에 따르면 라이선스는 아파치 2.0이고, 2026년 7월 중순 기준 최신 릴리스는 v1.0.136이다. 이 글은 macOS·리눅스·윈도우 터미널에서 OfficeCLI를 설치해 문서를 다루고, Claude Code 같은 AI 에이전트에 붙이는 데까지를 다룬다. 개별 문서 자동화 스크립트를 설계하는 방법은 범위에서 뺐다.
OfficeCLI는 무엇을 하는 도구인가
한 줄로 답하면, AI 에이전트가 오피스 문서를 사람 손을 거치지 않고 직접 다루도록 열어 주는 명령줄 도구다. CLI(터미널에 명령어를 입력해 프로그램을 조작하는 방식)로 .docx(워드)·.xlsx(엑셀)·.pptx(파워포인트) 세 포맷을 하나의 명령 체계 안에서 생성·조회·수정한다.
예전에는 워드는 python-docx, 엑셀은 openpyxl처럼 포맷마다 다른 라이브러리를 골라 코드를 짜야 했다. OfficeCLI는 이 셋을 같은 명령 문법으로 묶고, 내장 렌더링 엔진으로 문서를 HTML이나 PNG 이미지로 뽑아 눈으로 확인하게 한다. 공식 저장소 설명 기준으로 오피스 프로그램 자체를 깔 필요가 없고, 배포물은 의존성 없는 단일 바이너리다. 그래서 여러 갈래로 나뉘는 LLM 에이전트가 공통으로 마주치는 문제, 곧 오피스 문서를 어떻게 안정적으로 읽고 쓰느냐를 한 도구로 모은다.
설치와 버전 확인은 어떻게 하나
패키지 매니저가 있으면 한 줄이면 끝난다. macOS와 리눅스는 Homebrew나 npm, 윈도우는 PowerShell 설치 스크립트를 쓴다. 공식 저장소는 macOS(애플 실리콘·인텔), 리눅스(x64·ARM64), 윈도우(x64·ARM64)를 지원 대상으로 밝히고 있다.
# Homebrew (macOS·리눅스)
brew install officecli
# npm (공통)
npm install -g @officecli/officecli
# Windows PowerShell
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
# 설치가 끝났으면 버전 확인
officecli --version설치가 끝나면 officecli 명령이 PATH에 등록된다. officecli --version으로 버전이 찍히면 쓸 준비가 된 것이다.
문서를 만들고 읽고 고치는 기본 명령
명령은 대상 파일, 요소 경로, 동작 세 조각으로 짜인다. 요소 경로는 1부터 시작하는 번호로 위치를 가리키는데, /slide[1]/shape[2]는 첫 번째 슬라이드의 두 번째 도형을 뜻한다. XML 구조를 몰라도 이 경로만 알면 특정 요소를 짚을 수 있다.
| 명령어 | 하는 일 | 예시 |
|---|---|---|
| create | 빈 문서 생성 | officecli create deck.pptx |
| view | 내용 보기(outline·html·screenshot) | officecli view deck.pptx outline |
| query | 선택자로 요소 검색 | officecli query report.docx |
| add | 요소 추가 | officecli add deck.pptx / --type slide |
| set | 속성 수정 | officecli set deck.pptx 경로 --prop |
실제 작업은 대체로 이렇게 이어진다.
# 새 프레젠테이션 만들기
officecli create deck.pptx
# 첫 슬라이드를 추가하며 제목 넣기
officecli add deck.pptx / --type slide --prop title="Q4 리포트"
# 개요로 훑고, 특정 요소를 JSON으로 조회
officecli view deck.pptx outline
officecli get deck.pptx '/slide[1]/shape[1]' --json여기서 핵심은 --json 플래그다. 모든 명령에 --json을 붙이면 스키마가 일정한 구조화 출력을 내놓고, 오류도 not_found나 invalid_value 같은 코드가 담긴 객체로 돌려준다. 사람이 화면으로 읽기보다, 스크립트나 에이전트가 결과를 파싱해 다음 동작을 정하기 좋은 형태다.
고치면서 결과를 눈으로 확인하려면 watch를 띄워 둔다.
# 라이브 프리뷰 — 브라우저에서 http://localhost:26315 자동 갱신
officecli watch deck.pptx공식 저장소는 이 기능을 브라우저가 라이브 피드백 루프 역할을 한다고 설명한다. watch를 켜 두면 다른 터미널에서 add·set·remove 명령을 칠 때마다 미리보기 화면이 즉시 갱신되고, 엑셀 파일의 watch는 셀 인라인 편집까지 지원한다.
Claude Code·커서 같은 에이전트에 붙이기
OfficeCLI의 진짜 쓸모는 여기서 나온다. 에이전트가 문서 작업을 로컬 바이너리로 넘기도록 MCP(모델이 외부 도구를 호출하는 표준 통로) 서버를 붙이는 것이다. 연동은 도구별로 한 줄이다.
officecli mcp claude # Claude Code
officecli mcp cursor # Cursor
officecli mcp vscode # VS Code설치 과정에서 OfficeCLI는 Claude Code·GitHub Copilot·Codex의 설정 폴더를 감지해 스킬 파일(SKILL.md)을 자동으로 넣는다고 공식 저장소는 설명한다. 에이전트가 오피스 작업을 만나면 이 스킬을 따라 officecli 명령으로 경로를 잡는 식이다. 팀 지식을 CLAUDE.md와 스킬 파일로 남겨 두라는 접근과 결이 같아서, 문서 편집 능력을 에이전트에 상시로 얹어 둘 수 있다.
실무에 넣기 전 점검할 점
공식 저장소 기준으로 OfficeCLI는 v1.0.136을 7월 14일에 올렸고, 깃허브 스타는 2026년 7월 기준 약 1만 8천 6백 개다 — 2026년 3월 공개 후 넉 달 만의 수치다. 버전이 빠르게 오르는 초기 단계라 명령 이름이나 플래그가 바뀔 수 있으니, 자동화에 넣기 전 officecli --help로 현재 문법을 한 번 확인하는 편이 안전하다. 오픈소스라 명령 목록과 최신 변경은 공식 GitHub 저장소에서 직접 대조하면 된다. 터미널이 익숙하지 않은 팀원에게는 GUI 대안도 있다 — 공식 저장소에 따르면 같은 팀이 만든 데스크톱 앱 AionUi로 자연어 지시만으로 문서를 작성·편집할 수 있고, 내부에서는 OfficeCLI가 돌아간다.