# CLI SDK overview

> Understand how Univer CLI SDK adds a Node.js CLI and agent entry point to a Univer application.

- Human documentation: [https://office.univer.ai/cli/overview](https://office.univer.ai/cli/overview)

- Agent Markdown: [https://office.univer.ai/cli/overview.md](https://office.univer.ai/cli/overview.md)

- Language: `en`

- Source file: `content/docs/cli/overview.mdx`

- Upstream source: [https://github.com/dream-num/univer-cli-sdk/blob/main/README.md](https://github.com/dream-num/univer-cli-sdk/blob/main/README.md)

---

**Univer CLI SDK** is a TypeScript SDK for building Office CLIs. It gives agents and automation a Node.js entry point
for loading, understanding, changing, and checking Univer Units.

CLI SDK is a set of composable capabilities, not a fixed product CLI. The business application owns command names,
arguments, targets, identity and authorization, output, and deployment.

## Recommended application shape

This guide follows a `CLI + Web + Server` application:

```mermaid
flowchart LR
    Agent([Agent / CLI user]) --> CLI[Business CLI]
    Human([Human user]) --> Web[Web]
    CLI --> Server[Collaboration Server]
    Web --> Server
    Server --> Storage[(Storage)]
```

* CLI is the entry point for an agent or user operating a Unit.
* Web presents the actual page for interactive editing and human review.
* Server stores the Units, revisions, and collaboration state shared by CLI and Web.

CLI, Web, and Server can be deployed separately or run entirely locally. Building Web + Server with Collaboration SDK
before adding the CLI entry point is a recommended learning path, not a deployment restriction.

> **A CLI-only application is also supported**
>
> CLI SDK can process local Units directly. Results can be examined through structured output, agent
> visual checks, or exported Office files. Live Web pages, shared revisions, History, and Worktree
> require the corresponding Web and collaboration capabilities.

## Organize the CLI with Commander

CLI SDK base packages expose structured TypeScript APIs. Command preset packages turn common capabilities into native
Commander `Command` objects. The business application always owns the root program:

```ts
import { Command } from "commander";

const program = new Command("my-cli");

program.addCommand(presetCommand);
program.addCommand(applicationCommand);

await program.parseAsync();
```

* A **command preset** supplies default arguments, help, and text or JSON output.
* An **application command** composes Runtime, business targets, identity, commit policy, or file policy.
* Both are ordinary Commander `Command` objects and can be mixed in one root program.

Each following topic introduces the base capability first, then shows how it connects to Commander.

## Build capabilities progressively

The CLI SDK guide starts with core Unit content operations, then adds file, visual, collaboration, and process
capabilities:

```text
load and edit a Unit
→ Office file import and export
→ visual inspection
→ isolated Worktree editing and review
→ Runtime reuse and Daemon
```

### 1. Load and edit a Unit

First establish the minimum agent loop: load a Unit with Collaboration Runtime, understand it through Inspection,
execute Univer Facade code, and discover Facade APIs when needed.

### 2. Connect the Office file boundary

Use Univer Pro Exchange to convert between Office files and UnitData. Imported Units remain in the Collaboration
Server; export first obtains the latest UnitData through Collaboration Runtime.

### 3. Add visual inspection

Structured output cannot fully describe page layout. Screenshot gives the agent rendered images, while Layout Lint
provides structured layout diagnostics.

### 4. Isolate changes with Worktree

An agent can edit and check a Worktree draft through several rounds. When ready, a human reviews it in Web and chooses
Merge or Reopen.

### 5. Reuse expensive runtimes

Start with short-lived runtimes. Add a pool, workers, or daemon only when startup cost, concurrency, or reuse across CLI
processes becomes important.

## Recommended reading order

1. [Document loading and content operations](https://office.univer.ai/cli/content-operations.md)
2. [Office file import and export](https://office.univer.ai/cli/file-exchange.md)
3. [Visual inspection](https://office.univer.ai/cli/visual-inspection.md)
4. [Worktree: agent editing and human review](https://office.univer.ai/cli/worktree.md)
5. [Runtime reuse and Daemon](https://office.univer.ai/cli/runtime-architecture.md)
6. [Package catalog](https://office.univer.ai/cli/packages.md)
7. [Examples](https://office.univer.ai/cli/examples.md)