OfficeCLI/README_ko.md

OfficeCLI

OfficeCLI는 세계 최초이자 최고의, AI 에이전트를 위해 설계된 커맨드라인 도구입니다.

모든 AI 에이전트에게 Word, Excel, PowerPoint의 완전한 제어권을 — 단 한 줄의 코드로.

오픈소스. 단일 바이너리. Office 설치 불필요. 의존성 제로. 모든 플랫폼 지원.

English | 中文 | 日本語 | 한국어

AionUi에서 OfficeCLI로 PPT 제작 과정

PowerPoint 프레젠테이션

—

Word 문서

—

Excel 스프레드시트

위의 모든 문서는 AI 에이전트가 OfficeCLI를 사용하여 완전 자동으로 생성 — 템플릿 없음, 수동 편집 없음.

AI 에이전트용 — 한 줄로 시작

이 한 줄을 AI 에이전트 채팅에 붙여넣기만 하면 — 스킬 파일을 자동으로 읽고 설치를 완료합니다:

curl -fsSL https://officecli.ai/SKILL.md

이게 전부입니다. 스킬 파일이 에이전트에게 바이너리 설치 방법과 모든 명령어 사용법을 알려줍니다.

기술 세부사항: OfficeCLI에는 SKILL.md가 포함되어 있으며, 명령어 구문, 아키텍처, 자주 발생하는 실수를 다룹니다. 설치 후 에이전트는 즉시 Office 문서를 생성, 읽기, 수정할 수 있습니다.

일반 사용자용

옵션 A — GUI: AionUi를 설치하세요 — 자연어로 Office 문서를 만들고 편집할 수 있는 데스크톱 앱입니다. 내부적으로 OfficeCLI가 구동됩니다. 원하는 것을 설명하기만 하면 AionUi가 모든 것을 처리합니다.

옵션 B — CLI: GitHub Releases에서 플랫폼에 맞는 바이너리를 다운로드한 후 실행:

officecli install

바이너리를 PATH에 복사하고, 감지된 모든 AI 코딩 에이전트(Claude Code, Cursor, Windsurf, GitHub Copilot 등)에 officecli 스킬을 자동 설치합니다. 에이전트는 즉시 Office 문서를 생성, 읽기, 편집할 수 있으며 추가 설정이 필요 없습니다.

개발자용 — 30초 만에 라이브로 확인

# 1. 설치 (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

# 2. 빈 PowerPoint 생성
officecli create deck.pptx

# 3. 라이브 미리보기 시작 — 브라우저에서 http://localhost:26315 이 열립니다
officecli watch deck.pptx --port 26315

# 4. 다른 터미널을 열고 슬라이드 추가 — 브라우저가 즉시 업데이트됩니다
officecli add deck.pptx / --type slide --prop title="Hello, World!"

이게 전부입니다. add, set, remove 명령을 실행할 때마다 미리보기가 실시간으로 갱신됩니다. 계속 실험해 보세요 — 브라우저가 바로 여러분의 라이브 피드백 루프입니다.

빠른 시작

# 프레젠테이션을 생성하고 콘텐츠 추가
officecli create deck.pptx
officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
officecli add deck.pptx '/slide[1]' --type shape \
  --prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm \
  --prop font=Arial --prop size=24 --prop color=FFFFFF

# 개요 보기
officecli view deck.pptx outline
# → Slide 1: Q4 Report
# →   Shape 1 [TextBox]: Revenue grew 25%

# HTML로 보기 — 서버 없이 브라우저에서 렌더링된 미리보기를 엽니다
officecli view deck.pptx html

# 모든 요소의 구조화된 JSON 가져오기
officecli get deck.pptx '/slide[1]/shape[1]' --json

{
  "tag": "shape",
  "path": "/slide[1]/shape[1]",
  "attributes": {
    "name": "TextBox 1",
    "text": "Revenue grew 25%",
    "x": "720000",
    "y": "1800000"
  }
}

왜 OfficeCLI인가?

이전에는 50줄의 Python과 3개의 라이브러리가 필요했습니다:

from pptx import Presentation
from pptx.util import Inches, Pt
prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[0])
title = slide.shapes.title
title.text = "Q4 Report"
# ... 45줄 더 ...
prs.save('deck.pptx')

이제 명령어 하나면 됩니다:

officecli add deck.pptx / --type slide --prop title="Q4 Report"

OfficeCLI로 할 수 있는 것:

• 생성 문서 -- 빈 문서 또는 콘텐츠 포함
• 읽기 텍스트, 구조, 스타일, 수식 -- 일반 텍스트 또는 구조화된 JSON
• 분석 서식 문제, 스타일 불일치, 구조적 결함
• 수정 모든 요소 -- 텍스트, 글꼴, 색상, 레이아웃, 수식, 차트, 이미지
• 재구성 콘텐츠 -- 요소 추가, 삭제, 이동, 문서 간 복사

형식	읽기	수정	생성
Word (.docx)	✅	✅	✅
Excel (.xlsx)	✅	✅	✅
PowerPoint (.pptx)	✅	✅	✅

Word — 단락, 런, 표, 스타일, 머리글/바닥글, 이미지, 수식, 메모, 각주, 워터마크, 북마크, 목차, 차트, 하이퍼링크, 섹션, 양식 필드, 콘텐츠 컨트롤 (SDT), 필드, 문서 속성

Excel — 셀, 수식(150개 이상의 내장 함수 자동 계산), 시트, 테이블, 조건부 서식, 차트, 피벗 테이블 (다중 필드, 날짜 그룹화, showDataAs, 정렬, 총합계, 부분합), 이름 범위, 데이터 유효성 검사, 이미지, 스파크라인, 메모, 자동 필터, 도형, CSV/TSV 가져오기, $Sheet:A1 셀 주소 지정

PowerPoint — 슬라이드, 도형, 이미지, 표, 차트, 애니메이션, 모프 전환, 3D 모델 (.glb), 슬라이드 줌, 수식, 테마, 연결선, 비디오/오디오, 그룹, 노트, 플레이스홀더

사용 사례

개발자용:

• 데이터베이스나 API에서 보고서 자동 생성
• 문서 일괄 처리(일괄 검색/교체, 스타일 업데이트)
• CI/CD 환경에서 문서 파이프라인 구축(테스트 결과에서 문서 생성)
• Docker/컨테이너 환경에서의 헤드리스 Office 자동화

AI 에이전트용:

• 사용자 프롬프트에서 프레젠테이션 생성(위 예시 참조)
• 문서에서 구조화된 데이터를 JSON으로 추출
• 납품 전 문서 품질 검증

팀용:

• 문서 템플릿을 복제하고 데이터 입력
• CI/CD 파이프라인에서 자동 문서 검증

설치

단일 자체 완결형 바이너리로 제공. .NET 런타임 내장 -- 설치할 것도, 관리할 런타임도 없습니다.

원라인 설치:

# 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

또는 수동 다운로드 GitHub Releases:

플랫폼	바이너리
macOS Apple Silicon	officecli-mac-arm64
macOS Intel	officecli-mac-x64
Linux x64	officecli-linux-x64
Linux ARM64	officecli-linux-arm64
Windows x64	officecli-win-x64.exe
Windows ARM64	officecli-win-arm64.exe

설치 확인: officecli --version

또는 다운로드한 바이너리에서 셀프 설치 (officecli를 직접 실행해도 설치가 트리거됩니다):

officecli install    # 명시적 설치
officecli            # 직접 실행으로도 설치 트리거

업데이트는 백그라운드에서 자동 확인됩니다. officecli config autoUpdate false로 비활성화하거나 OFFICECLI_SKIP_UPDATE=1로 단일 실행 시 건너뛸 수 있습니다. 설정은 ~/.officecli/config.json에 있습니다.

주요 기능

라이브 미리보기

watch는 로컬 HTTP 서버를 시작하여 PowerPoint 파일의 라이브 HTML 미리보기를 제공합니다. 수정할 때마다 브라우저가 자동 새로고침 — AI 에이전트와의 반복 디자인에 최적입니다.

officecli watch deck.pptx
# http://localhost:26315 열기 — set/add/remove 시마다 자동 새로고침

도형, 차트, 수식, 3D 모델(Three.js), 모프 전환, 줌 내비게이션, 모든 도형 효과를 렌더링합니다.

레지던트 모드와 배치

다단계 워크플로우에서 레지던트 모드는 문서를 메모리에 유지합니다. 배치 모드는 한 번의 open/save 사이클에서 여러 작업을 실행합니다.

# 레지던트 모드 — 명명된 파이프로 거의 제로 지연
officecli open report.docx
officecli set report.docx /body/p[1]/r[1] --prop bold=true
officecli set report.docx /body/p[2]/r[1] --prop color=FF0000
officecli close report.docx

# 배치 모드 — 원자적 다중 명령 실행 (기본적으로 첫 오류에서 중지)
echo '[{"command":"set","path":"/slide[1]/shape[1]","props":{"text":"Hello"}},
      {"command":"set","path":"/slide[1]/shape[2]","props":{"fill":"FF0000"}}]' \
  | officecli batch deck.pptx --json

# 인라인 배치 — stdin 불필요
officecli batch deck.pptx --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hi"}}]'

# --force로 오류를 건너뛰고 계속 실행
officecli batch deck.pptx --input updates.json --force --json

3계층 아키텍처

간단하게 시작하고, 필요할 때만 깊이 들어가세요.

레이어	용도	명령어
L1: 읽기	콘텐츠의 시맨틱 뷰	view (text, annotated, outline, stats, issues, html)
L2: DOM	구조화된 요소 작업	get, query, set, add, remove, move, swap
L3: 원시 XML	XPath 직접 접근 — 범용 폴백	raw, raw-set, add-part, validate

# L1 — 고수준 뷰
officecli view report.docx annotated
officecli view budget.xlsx text --cols A,B,C --max-lines 50

# L2 — 요소 수준 작업
officecli query report.docx "run:contains(TODO)"
officecli add budget.xlsx / --type sheet --prop name="Q2 Report"
officecli move report.docx /body/p[5] --to /body --index 1

# L3 — L2로 부족할 때 원시 XML
officecli raw deck.pptx '/slide[1]'
officecli raw-set report.docx document \
  --xpath "//w:p[1]" --action append \
  --xml '<w:r><w:t>Injected text</w:t></w:r>'

AI 통합

MCP 서버

내장 MCP 서버 — 명령어 하나로 등록:

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

JSON-RPC로 모든 문서 작업을 제공 — 셸 접근 불필요.

직접 CLI 통합

2단계로 OfficeCLI를 모든 AI 에이전트에 통합:

1. 바이너리 설치 -- 명령어 하나 (설치 참조)
2. 완료. OfficeCLI가 AI 도구(Claude Code, GitHub Copilot, Codex)를 자동 감지하고, 알려진 설정 디렉토리를 확인하여 스킬 파일을 설치합니다. 에이전트는 즉시 Office 문서를 생성, 읽기, 수정할 수 있습니다.

수동 설정 (선택사항)

자동 설치가 환경을 지원하지 않는 경우, 스킬 파일을 수동으로 설치할 수 있습니다:

SKILL.md를 에이전트에 직접 제공:

curl -fsSL https://officecli.ai/SKILL.md

Claude Code 로컬 스킬로 설치:

curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md

기타 에이전트: SKILL.md의 내용을 에이전트의 시스템 프롬프트 또는 도구 설명에 포함하세요.

모든 언어에서 호출:

# Python
import subprocess, json
def cli(*args): return subprocess.check_output(["officecli", *args], text=True)
cli("create", "deck.pptx")
cli("set", "deck.pptx", "/slide[1]/shape[1]", "--prop", "text=Hello")

// JavaScript
const { execFileSync } = require('child_process')
const cli = (...args) => execFileSync('officecli', args, { encoding: 'utf8' })
cli('set', 'deck.pptx', '/slide[1]/shape[1]', '--prop', 'text=Hello')

모든 명령어가 --json으로 구조화된 출력을 지원합니다. 경로 기반 주소 지정으로 에이전트가 XML 네임스페이스를 이해할 필요가 없습니다.

에이전트가 OfficeCLI를 선호하는 이유

• 결정론적 JSON 출력 -- 모든 명령어가 --json을 지원하며, 일관된 스키마의 구조화된 데이터를 반환. 정규식 파싱 불필요.
• 경로 기반 주소 지정 -- 모든 요소가 안정적인 경로를 가짐(/slide[1]/shape[2]). XML 네임스페이스를 이해하지 않고도 문서 탐색 가능. 참고: 경로는 OfficeCLI 고유 구문(1부터 시작하는 인덱스, 요소 로컬 이름)을 사용하며, XPath가 아닙니다.
• 단계적 복잡성 -- L1(읽기)에서 시작, L2(수정)로 확대, 필요할 때만 L3(원시 XML)로 폴백. 토큰 소비 최소화.
• 자가 치유 워크플로우 -- validate, view issues, 도움말 시스템으로 에이전트가 사람의 개입 없이 문제를 감지하고 자체 수정 가능.
• 내장 도움말 -- 속성 이름이나 값 형식이 불확실할 때 officecli <format> set <element>을 실행하여 확인. 추측 불필요.
• 자동 설치 -- 스킬 파일 수동 설정 불필요. OfficeCLI가 AI 도구를 자동 감지하고 설정 완료.

내장 도움말

속성 이름을 모를 때, 계층형 도움말로 확인:

officecli pptx set              # 모든 설정 가능한 요소와 속성
officecli pptx set shape        # 특정 요소 유형의 세부사항
officecli pptx set shape.fill   # 단일 속성 형식과 예시
officecli docx query            # 셀렉터 참조: 속성, :contains, :has() 등

pptx를 docx나 xlsx로 대체 가능. 동사는 view, get, query, set, add, raw.

officecli --help로 전체 개요 확인.

JSON 출력 스키마

모든 명령어가 --json을 지원합니다. 일반적인 응답 형식:

단일 요소 (get --json):

{"tag": "shape", "path": "/slide[1]/shape[1]", "attributes": {"name": "TextBox 1", "text": "Hello"}}

요소 목록 (query --json):

[
  {"tag": "paragraph", "path": "/body/p[1]", "attributes": {"style": "Heading1", "text": "Title"}},
  {"tag": "paragraph", "path": "/body/p[5]", "attributes": {"style": "Heading1", "text": "Summary"}}
]

오류는 구조화된 오류 객체를 반환합니다. 오류 코드, 수정 제안, 사용 가능한 값을 포함:

{
  "success": false,
  "error": {
    "error": "Slide 50 not found (total: 8)",
    "code": "not_found",
    "suggestion": "Valid Slide index range: 1-8"
  }
}

오류 코드: not_found, invalid_value, unsupported_property, invalid_path, unsupported_type, missing_property, file_not_found, file_locked, invalid_selector. 속성 이름은 자동 교정 지원 -- 속성 이름 오타 시 가장 근접한 매칭을 제안합니다.

오류 복구 -- 에이전트가 사용 가능한 요소를 확인하여 자체 수정:

# 에이전트가 잘못된 경로 시도
officecli get report.docx /body/p[99] --json
# 반환: {"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}}

# 에이전트가 사용 가능한 요소를 확인하여 자체 수정
officecli get report.docx /body --depth 1 --json
# 사용 가능한 하위 요소 목록 반환, 에이전트가 올바른 경로 선택

변경 확인 (set, add, remove, move, create에서 --json 사용 시):

{"success": true, "path": "/slide[1]/shape[1]"}

officecli --help로 종료 코드와 오류 형식의 전체 설명 확인.

비교

	OfficeCLI	Microsoft Office	LibreOffice	python-docx / openpyxl
오픈소스 & 무료	✓ (Apache 2.0)	✗ (유료 라이선스)	✓	✓
AI 네이티브 CLI + JSON	✓	✗	✗	✗
제로 설치 (단일 바이너리)	✓	✗	✗	✗ (Python + pip 필요)
모든 언어에서 호출	✓ (CLI)	✗ (COM/Add-in)	✗ (UNO API)	Python만
경로 기반 요소 접근	✓	✗	✗	✗
원시 XML 폴백	✓	✗	✗	부분 지원
라이브 미리보기	✓	✓	✗	✗
헤드리스 / CI	✓	✗	부분 지원	✓
크로스 플랫폼	✓	Windows/Mac	✓	✓
Word + Excel + PowerPoint	✓	✓	✓	여러 라이브러리 필요

업데이트 및 설정

officecli config autoUpdate false              # 자동 업데이트 확인 비활성화
OFFICECLI_SKIP_UPDATE=1 officecli ...          # 단일 실행 시 확인 건너뛰기 (CI)

명령어 참조

명령어	설명
create	빈 .docx, .xlsx, .pptx 생성 (확장자로 유형 결정)
view	콘텐츠 보기 (모드: outline, text, annotated, stats, issues, html)
get	요소와 하위 요소 가져오기 (--depth N, --json)
query	CSS 스타일 쿼리 ([attr=value], :contains(), :has() 등)
set	요소 속성 수정
add	요소 추가 (또는 --from <path>로 복제)
remove	요소 삭제
move	요소 이동 (--to <parent>, --index N, --after <path>, --before <path>)
swap	두 요소 교체
validate	OpenXML 스키마 검증
batch	한 번의 open/save 사이클에서 여러 작업 실행 (stdin, --input, 또는 --commands; 기본적으로 첫 오류에서 중지, --force로 계속)
merge	템플릿 병합 — {{key}} 플레이스홀더를 JSON 데이터로 교체
watch	브라우저에서 라이브 HTML 미리보기, 자동 새로고침
mcp	AI 도구 통합용 MCP 서버 시작
raw	문서 파트의 원시 XML 보기
raw-set	XPath로 원시 XML 수정
add-part	새 문서 파트 추가 (머리글, 차트 등)
open	레지던트 모드 시작 (문서를 메모리에 유지)
close	저장하고 레지던트 모드 종료
install	바이너리 + 스킬 + MCP 설치 (all, claude, cursor 등)
config	설정 가져오기 또는 변경
<format> <command>	내장 도움말 (예: officecli pptx set shape)

엔드투엔드 워크플로우 예시

전형적인 에이전트 자가 치유 워크플로우: 프레젠테이션 생성, 콘텐츠 입력, 검증, 문제 수정 -- 모두 사람의 개입 없이.

# 1. 생성
officecli create report.pptx

# 2. 콘텐츠 추가
officecli add report.pptx / --type slide --prop title="Q4 Results"
officecli add report.pptx '/slide[1]' --type shape \
  --prop text="Revenue: $4.2M" --prop x=2cm --prop y=5cm --prop size=28
officecli add report.pptx / --type slide --prop title="Details"
officecli add report.pptx '/slide[2]' --type shape \
  --prop text="Growth driven by new markets" --prop x=2cm --prop y=5cm

# 3. 검증
officecli view report.pptx outline
officecli validate report.pptx

# 4. 문제 수정
officecli view report.pptx issues --json
# 출력에 따라 문제 수정:
officecli set report.pptx '/slide[1]/shape[1]' --prop font=Arial

템플릿 병합

문서 내 {{key}} 플레이스홀더를 JSON 데이터로 교체 -- 단락, 표 셀, 도형, 머리글, 바닥글, 차트 제목 등 모든 텍스트 콘텐츠 지원.

# 인라인 JSON 데이터
officecli merge template.docx output.docx '{"name":"Alice","dept":"Sales","date":"2026-03-30"}'

# JSON 파일에서 읽기
officecli merge template.pptx report.pptx data.json

# Excel 템플릿
officecli merge budget-template.xlsx q4-budget.xlsx '{"quarter":"Q4","year":"2026"}'

단위와 색상

모든 치수 및 색상 속성은 유연한 입력 형식을 지원:

유형	지원 형식	예시
치수	cm, in, pt, px 또는 원시 EMU	2cm, 1in, 72pt, 96px, 914400
색상	16진수, 색상 이름, RGB, 테마 색상	#FF0000, FF0000, red, rgb(255,0,0), accent1
글꼴 크기	숫자만 또는 pt 접미사	14, 14pt, 10.5pt
간격	pt, cm, in 또는 배율	12pt, 0.5cm, 1.5x, 150%

자주 사용하는 패턴

# Word 문서의 모든 Heading1 텍스트 교체
officecli query report.docx "paragraph[style=Heading1]" --json | ...
officecli set report.docx /body/p[1]/r[1] --prop text="New Title"

# 모든 슬라이드 콘텐츠를 JSON으로 내보내기
officecli get deck.pptx / --depth 2 --json

# Excel 셀 일괄 업데이트
officecli batch budget.xlsx --input updates.json --json

# CSV 데이터를 Excel 시트로 가져오기
officecli add budget.xlsx / --type sheet --prop name="Q1 Data" --prop csv=sales.csv

# 템플릿 병합으로 보고서 일괄 생성
officecli merge invoice-template.docx invoice-001.docx '{"client":"Acme","total":"$5,200"}'

# 납품 전 문서 품질 확인
officecli validate report.docx && officecli view report.docx issues --json

문서

Wiki에서 모든 명령어, 요소 유형, 속성의 상세 가이드를 확인하세요:

• 형식별: Word | Excel | PowerPoint
• 워크플로우: 엔드투엔드 예시 -- Word 보고서, Excel 대시보드, PPT 프레젠테이션, 일괄 수정, 레지던트 모드
• 문제 해결: 자주 발생하는 오류와 해결책
• AI 에이전트 가이드: Wiki 내비게이션 결정 트리

소스에서 빌드

컴파일에는 .NET 10 SDK가 필요합니다. 출력은 자체 완결형 네이티브 바이너리 -- .NET이 내장되어 있어 실행 시 설치 불필요.

./build.sh

라이선스

Apache License 2.0

버그 리포트와 기여는 GitHub Issues로 환영합니다.

---

OfficeCLI가 유용하다면 GitHub에서 스타를 눌러주세요 — 더 많은 사람들이 프로젝트를 발견하는 데 도움이 됩니다.

OfficeCLI.AI | GitHub