2 min

CLI SDK overview

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

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:

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.

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:

TypeScript

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.