# CLI

> 기존 에이전트에 로컬 Office 기능을 연결하세요. 설치 후 예제를 열고 계산·편집·검토할 결과물을 만듭니다.

- Human documentation: [https://docs.univer.ai/ko-KR/overview/examples/cli](https://docs.univer.ai/ko-KR/overview/examples/cli)

- Agent Markdown: [https://docs.univer.ai/ko-KR/overview/examples/cli.md](https://docs.univer.ai/ko-KR/overview/examples/cli.md)

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.3.0`

- Source: [examples/cli.ko-KR.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/examples/cli.ko-KR.mdx)

---

**Univer CLI**는 **[Univer Office SDK](https://docs.univer.ai/ko-KR/overview.md)**로 만든 로컬 Office 자동화 앱입니다. 기존 에이전트에 명령과 Skills를 제공해 Excel, Word, PowerPoint를 처리하거나 표, 문서, 프레젠테이션, 관계형 테이블, 캔버스를 만듭니다. 결과는 로컬에 저장됩니다.

**현재 Univer를 조작하는 주된 방식은 CLI(Command-Line Interface, 명령줄 인터페이스)입니다**. 기존 MCP 중심의 Agent 연동을 대신해 Univer CLI가 `univer` 명령과 Skills를 제공합니다. Agent는 자신의 명령 실행 환경에서 콘텐츠를 편집·검사·전달하고, 로컬 Viewer에서 결과를 미리 보고 검토할 수 있습니다.

[설치 및 체험](#quick-start) · [Skills 작동 방식](#skills) · [Skills 목록](#skills-catalog)

## 이미 사용하는 에이전트와 연결

다음 에이전트에서 Univer CLI를 사용할 수 있습니다.

**OpenCode** · **Claude Code** · **OpenClaw** · **Hermes** · **Codex** · **WorkBuddy** · **Kimi Work**

공통 진입점은 `univer` 명령과 버전에 맞는 사용 지침입니다. Agent Skills 지원 호스트는 공식 Skill을 로드하고, 명령 실행이 가능한 에이전트는 자체 도구 계층으로 호출할 수 있습니다. 대화 안 미리 보기 카드 등 호스트별 경험은 [통합 프로젝트](https://univer.ai/ecosystem)를 참고하세요.

## 첫 결과물 확인하기

Node.js 24 이상을 준비하고 에이전트가 사용하는 환경에 설치하세요.

```bash
npm install --global univer-cli@latest
npx skills add dream-num/skills -s univer-cli -g
univer doctor
```

`univer doctor`는 로컬 실행 환경을 확인합니다. Skill은 명령 검색, 제품별 지침 로드, 콘텐츠 검사와 전달을 안내합니다.

### 공식 예제 열기

새 빈 디렉터리에서 에이전트에게 다음을 보내세요.

```text
Univer CLI로 공식 예제를 체험해 주세요.
https://univer.ai/cli-assets/hello.univer 를 현재 폴더의 hello.univer로 내려받으세요.
파일의 콘텐츠 목록과 로컬 Viewer 링크를 주고 무엇을 체험할 수 있는지 설명해 주세요.
```

기존 콘텐츠를 열면 네이티브 편집기를 바로 체험할 수 있습니다. 이후 수정을 요청하거나 아래 생성 작업을 시도하세요.

## Skills: 에이전트를 위한 작업 가이드

Skills는 콘텐츠 모델, 편집 절차, Facade API 검색과 검증 요구 사항을 에이전트가 읽을 수 있는 가이드로 제공합니다. 작업에 필요한 기능을 찾고 편집부터 검토와 결과 전달까지 진행할 수 있도록 돕습니다.

**탐색 진입점:** 에이전트에 설치하는 [`univer-cli` Skill](https://github.com/dream-num/skills/blob/main/skills/univer-cli/SKILL.md)은 Office 작업을 식별하고 로컬 CLI에서 전체 가이드를 불러오도록 안내합니다.

**런타임 Skills:** CLI와 함께 배포되며 설치된 버전의 명령 및 Facade API와 일치합니다. 먼저 `core`, 다음으로 대상 제품을 불러오고, 임베드나 콘텐츠 간 수식을 사용하면 해당 주제를 추가합니다.

### 작업에 맞게 불러오기

보통 에이전트가 직접 읽지만 개발자도 다음 명령으로 확인할 수 있습니다.

```bash
univer skills list
univer skills get core
univer skills get sheet
univer skills path sheet
```

`list`는 설치된 Skills를 나열하고, `get`은 가이드를 읽고, `path`는 로컬 디렉터리를 반환합니다. 참고 자료와 템플릿이 필요하면 `univer skills get core --full`을 사용합니다. 개별 API는 `univer api find`와 `univer api show`로 필요할 때 검색합니다.

### Skills 목록

이름을 클릭하면 소스의 가이드를 볼 수 있습니다. 실제 작업에서는 로컬 `univer skills get <name>`이 반환하는 버전을 사용하세요.

| Skill | 사용하는 경우 |
| --- | --- |
| [`core`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/core/SKILL.md) | 공통 작업 흐름: Unit과 Worktree 이해, 콘텐츠 찾기, 편집, 검증, 검토용 결과 전달. |
| [`sheet`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/sheet/SKILL.md) | 스프레드시트(Sheet): 데이터, 수식, 서식, 차트와 결과 검증. |
| [`doc`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/doc/SKILL.md) | 문서(Doc): 단락, 서식 있는 텍스트, 표, 차트와 페이지 레이아웃. |
| [`slide`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/slide/SKILL.md) | 프레젠테이션(Slide): 페이지, 도형, 텍스트, 이미지와 시각적 검증. |
| [`base`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/base/SKILL.md) | Relational Table: 테이블, 필드, 레코드와 뷰. |
| [`board`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/board/SKILL.md) | Canvases: 캔버스 요소, 차트와 레이아웃 검증. |
| [`embed`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/embed/SKILL.md) | 임베드: 다른 Unit의 콘텐츠를 삽입하고 차트 데이터 소스를 연결. |
| [`cross-unit-formula`](https://github.com/dream-num/univer-cli/blob/main/apps/cli/src/skills/runtime/cross-unit-formula/SKILL.md) | 콘텐츠 간 수식: Sheet 범위나 Relational Table 필드의 데이터를 Sheet 셀 또는 수식 기반 도형에서 계산. |

예를 들어 문서에 스프레드시트를 삽입하려면 `core → doc + sheet → embed` 순서로 불러옵니다. Sheet 셀이나 도형에서 다른 콘텐츠의 데이터를 참조할 때는 `cross-unit-formula`를 추가합니다. 모든 가이드를 처음부터 불러올 필요는 없습니다. CLI 업데이트 후에는 `core`와 관련 제품 및 주제 Skills를 다시 불러오세요.

## 무엇을 만들 수 있나요

- **데이터를 결과물로:** 표 정리, 수식, 차트, 피벗 테이블부터 머리글·바닥글이 있는 보고서와 개요 기반 프레젠테이션까지 만들 수 있습니다.
- **콘텐츠 연결:** 하나의 `.univer` 파일에 여러 콘텐츠를 담고 수식, 차트 참조, 임베드로 연결합니다.
- **생성 후 검증:** Facade로 실제 모델을 다시 읽고 스크린샷과 슬라이드 레이아웃 검사로 넘침, 겹침, 페이지 밖 텍스트를 확인합니다.
- **검토 후 전달:** 에이전트는 격리된 Worktree에서 작업하고 로컬 Viewer 링크를 반환합니다. 차이를 검토하고 수정·병합·폐기한 뒤 지원되는 Office 형식으로 내보낼 수 있습니다. 캔버스 파일 가져오기·내보내기는 아직 지원하지 않습니다.

## 이런 작업을 요청해 보세요

> Univer CLI로 날짜, 분류, 금액과 예제 5행이 있는 월별 지출표를 만들어 주세요. 합계 수식과 분류별 차트를 추가하고 데이터·화면을 검사해 Viewer 링크를 주세요. 검토 전에는 병합하지 마세요.

## Office SDK가 담당하는 부분

Office SDK는 Headless 콘텐츠 실행 환경, Facade API, 계산, 렌더링, 버전과 Worktree를 제공합니다. CLI는 이를 터미널 명령과 버전에 맞는 Skills로 구성하고 로컬 `.univer` 저장소, Gateway, Viewer를 관리합니다. 에이전트가 만든 콘텐츠를 편집기에서 미리 보고 표준 파일로 전달할 수 있습니다.

## 체험과 소스 코드

[빠른 시작](https://github.com/dream-num/univer-cli#quick-start) · [소스 저장소](https://github.com/dream-num/univer-cli)

## 관련 기능 살펴보기

- [헤드리스 및 서버 계산](https://docs.univer.ai/ko-KR/overview/features/shared/server-calculation.md)
- [문서 로드와 콘텐츠 작업](https://docs.univer.ai/ko-KR/ai/content-operations.md)
- [Worktree](https://docs.univer.ai/ko-KR/overview/features/shared/worktree.md)

[모든 예제](https://docs.univer.ai/ko-KR/overview/examples.md)