# Univer Cli

> Use when working with `.univer` targets, Univer CLI commands, worktrees, SaC sidecars, managed inspect tools, migration packs, spreadsheet formulas/formatting/charts, preview, worktree merge, import/export, or Excel-compatible handoff.

- **Type:** Skill
- **Install:** `agentstack add skill-dream-num-skills-univer-cli`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dream-num](https://agentstack.voostack.com/s/dream-num)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [dream-num](https://github.com/dream-num)
- **Source:** https://github.com/dream-num/skills/tree/main/skills/univer-cli
- **Website:** https://univer.ai

## Install

```sh
agentstack add skill-dream-num-skills-univer-cli
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Univer CLI

`univer` is a terminal-native univerfile engine. Use this skill to choose the public CLI and SaC
surfaces for target evidence, durable `.univer` changes, verification, preview, worktree review, and
handoff. Use `univer help` and `univer help ` for exact command syntax.

## Core Model

Treat target-visible unit state as the source of truth. Command success, metadata, local notes, or
generated source do not prove that sheets, values, formulas, formatting, charts, resources, or
handoff files are correct.

A `.univer` path is the univerfile you work on: the authoritative store for that file's units. Pick
one explicit path such as `./Budget.univer` and pass it to commands, including `status`. Do not
target work by `sessionId`, runtime id, display name, sheet name, or the current directory.

Each univerfile has two scopes. `trunk` is the authoritative mainline a person sees and may edit. A
`worktree` is an isolated copy where agents do work so it can be reviewed before it touches trunk.
Scope commands — the reads (`inspect`, `status`, `export`, `open`) and the SaC write path (`apply`,
`rollback`, `verify`, `materialize`) — require `--worktree ` to name the worktree. `new` creates
on trunk and takes no `--worktree`, and `worktree create`/`list` act on the whole univerfile. Scope
is stateless: there is no "current worktree" checkout, so `--worktree ` is mandatory on every
scope command and parallel agents never cross scopes. A worktree changes only through SaC; its work
reaches trunk only through `worktree merge`.

Typical loop: do the user's task on a worktree, mark it ready with `worktree ready`, then `open` it
to give the user a viewer link. The user reviews and chooses to merge or discard — from that viewer
page or via `worktree merge` / `worktree discard`. Merging into trunk is normally the user's
decision, not an automatic agent step.

Before acting on a follow-up, re-check with `worktree list`, because the user may have merged,
discarded, or only reviewed in the browser. If its `status` is still `open`/`ready` and the message
refines the same change, keep working there — more SaC returns a `ready` worktree to the `open`
status; when done, mark it `ready` and hand off a fresh link with `univer open`. Use a new worktree for a
merged or discarded one, or for a separate task.

A `.univer` file holds top-level units; `unitId` identifies a unit inside it. Sheet names, A1
ranges, values, formulas, styles, tables, filters, charts, shapes, and images are coordinates or
resources inside a selected unit.

Use public surfaces for reads and writes. A `.univer` univerfile is not an agent-handwritten source
file; do not bypass the CLI/SaC surfaces to patch it by hand.

## Public Surfaces

| Need | Use |
| --- | --- |
| Create or import univerfiles | `new` (trunk), `import` |
| Isolate work for review | `worktree create`, then work under a required `--worktree ` |
| Read target evidence | task-local route contract when present; otherwise focused managed `inspect --tool`; custom readonly `inspect --script` only for bounded aggregation/comparison gaps |
| Make durable changes | `sac materialize`, `sac migration create`, source edits, `sac apply`, `sac verify` |
| Recover an applied SaC boundary | `sac rollback` |
| Check scope state | `status` |
| Land or drop a worktree | `worktree ready`, `worktree merge`, `worktree discard` |
| Review or hand off visually | `open`, `view comments`, browser tools |
| Produce Excel-compatible output | `export` after verifying the relevant target-visible state |

## Tool Loop Budget

Prefer one reusable evidence artifact over repeated equivalent commands. After `units`,
`sheet-overview`, `sheet-range --out`, materialize, or verify writes an artifact path, read that
artifact with bounded `jq`/`sed` before rerunning the same discovery command. Refresh evidence only
after target state changes such as `sac apply`, rollback, restore, reset, import/export roundtrip,
or an explicitly new range/sheet question.

Do not begin common range read/write/format/assertion tasks with lookup when the needed command or
API pattern is already known. Use lookup and references as bounded fallback for one diagnostic-driven
gap such as a missing API, unknown helper, argument shape, or specific unresolved symbol. If a
primitive lookup result gives the API, minimal source shape, and read hint you need, author or verify
next. Read a declaration or reference file only when a new failure, unfamiliar command surface, or
missing API detail names that specific gap.

For large-table or cross-range facts, prefer one reusable managed artifact plus bounded shell reads
first. Use a custom readonly inspect script only after that artifact cannot answer a concrete
aggregation/comparison question without repeated broad reads. One sidecar-local probe should return
compact facts such as counts, grouped totals, mismatches, candidate ranges, and head/tail samples.
Do not use a custom probe to mutate workbook state, read `.univer` internals, encode out-of-band
correctness data or external expected answers, or write durable migration/assertion source.

## Lookup Protocol

Use `univer lookup` for CLI-owned API/type/manual discovery, not workbook-visible facts. Workbook
facts still belong to managed `univer inspect` tools. Lookup is a fallback, not the default first
step for ordinary range read/write/format/assertion work when the known pattern is sufficient.

Prefer short primitive lookup queries with 2-3 words:

```bash
univer lookup "range read"
univer lookup "range write"
univer lookup "range clear"
univer lookup "range address"
```

Use exact-symbol lookup when you need a precise declaration:

```bash
univer lookup "FRange.getValues"
univer lookup "FRange.setValues"
```

Do not paste a whole task prompt into lookup. Bad queries include
`range set values clear content spreadsheet facade` or long worksheet instructions that mix read,
write, clear, format, assertion, and workbook evidence in one search. Split complex tasks into
primitive lookups, then follow the returned `Read` hints.

Lookup text output is the public agent-facing contract. It includes `Query`, `Mode`, optional
`Suggested queries`, and `Read` sections. Do not use `univer lookup ... --json` or request another
machine-readable lookup format.

Fallback lookup flow:

1. Start lookup only after a typecheck/apply/verify/command diagnostic or genuinely unfamiliar
   command surface names the immediate API/detail gap. If the common pattern is already known, skip
   lookup and author or verify.
2. Use one short primitive query for that gap, such as `univer lookup "range values"`,
   `univer lookup "display values"`, or `univer lookup "set number format"`.
3. Read the text sections. Use `Read` commands for exact declaration lines, and use `Suggested
   queries` only when lookup reports `Mode: decompose`.
4. For compound spreadsheet tasks, follow shorter suggested primitive lookups only for still-open
   API gaps instead of trying to make one broad lookup cover reading, writing, formatting, and
   assertions.

Stop lookup once the immediate API gap is closed. A successful primitive lookup such as
`range write`, `range clear`, `number format`, or `range style` should usually be followed by
authoring or evidence work, not adjacent lookup expansion. Use exact-symbol lookup only when a
specific declaration is still ambiguous or a typecheck/apply failure points at that API.

Lookup read hints are designed to work with shell tools. Use the returned `sed -n` command or exact
location to read the declaration lines you need; avoid broad `rg` over all `types/*.d.ts` or full
type-file reads when short lookup or exact-symbol lookup can bound the context.

## Task-Local Route Contracts

Some harnesses or task workspaces provide a local route contract, classifier, first-tool policy,
fallback gates, or hard stops. Treat that task-local contract as the route owner. This skill supplies
reusable Univer CLI surfaces, product invariants, and diagnostic fallback guidance; do not turn it
into an additional route checklist to satisfy alongside the task-local contract.

When no task-local route owner exists, choose the least expensive product evidence for the unknown
fact:

- Small bounded edits should start with unit/sheet discovery and one focused target-visible read.
- Large table, grouped, dedupe, aggregate, matching, summary, or cross-range transforms may use
  materialized source, migration source, TSV/table previews, or sidecar docs to form a bounded
  hypothesis, but those sources are not target truth.
- Rich text, merge, semantic style, conditional format, active sheet, unsupported include, or similar
  capability ambiguity should use one focused target evidence read and one capability/API check, then
  choose a supported representation or report the gap.
- API discovery belongs after typecheck, apply, verify, or command diagnostics name a missing method,
  unknown helper, argument shape, overload, enum, assertion helper shape, or unfamiliar command
  surface.

For large transforms, use source evidence only to answer a bounded question that would otherwise
require broad target reads or repeated artifact probing. Confirm decision-relevant facts with
target-visible evidence before handoff. Do not use row count alone to trigger custom scripts. If one
managed artifact plus bounded shell reads still leaves a concrete aggregation/comparison gap, write
one readonly sidecar-local custom inspect aggregation script before another broad managed range read.
Return compact JSON facts such as source shape, target shape, operation type, candidate count,
output count, write range, head/tail samples, preservation samples, and assertion plan.

First-pass assertions should prioritize the requested output cells/ranges. Add at
most one or two preservation invariants directly tied to the mutation risk. Keep source rationale,
active sheet, broad style preservation, and non-output facts as readback notes unless the task
explicitly requires them.

## Evidence Tools

Managed inspect tools are the preferred readonly evidence surface. A unit-scoped `inspect` reads the
worktree named by the required `--worktree `; the `inspect tools` registry commands take no
scope. Use them for target inventory, sheet names, used ranges, focused range readback,
search/neighborhood confirmation, formulas, display/logical value differences, number formats, and
stable style traits. Avoid broad managed range dumps as first discovery for small bounded edits, and
switch to custom aggregation before repeated broad reads for large transforms. Discover units before
unit-scoped reads, and resolve tool params when a tool shape is unclear:

```bash
UNIVERFILE=./Budget.univer
univer inspect tools list --json
univer inspect tools resolve sheet-range --json
printf '%s' '{}' > ./units.params.json
univer inspect "$UNIVERFILE" --tool units --worktree "$WORKTREE_ID" --params ./units.params.json --out ./units.result.json
printf '%s' '{"unitId":"...","sheetName":"","rangeA1":"A1:D20"}' \
  > ./range.params.json
univer inspect "$UNIVERFILE" --tool sheet-range --worktree "$WORKTREE_ID" --params ./range.params.json --out ./range.result.json
```

Do not assume a default sheet name such as `Sheet1`. Read the actual sheet names from `units` or
`sheet-overview` first, then copy the exact returned name in `sheetName`, `getSheetByName(...)`,
and assertion `range()` targets. Sheet names are exact identifiers: do not title-case, lowercase,
trim internal spaces, translate, or otherwise normalize them. If an inspect diagnostic includes a
`didYouMean` sheet name, rerun the same bounded evidence request with that exact name instead of
continuing to guess.

`--params` accepts either a real JSON file path or `-` for stdin. Prefer real params files when the
command will be reused. Do not pass `/dev/stdin`, inline JSON, or a missing temp path as the option
value; `--params '{}'` is interpreted as a file path named `{}`.

For reusable or large evidence, use `--out ./name.result.json`. The CLI writes the complete result
as pretty JSON and prints a short Agent Index Output with the artifact path, warning/truncation
status, and stable `jq` read hints. Reuse that result file with `jq` or bounded `sed` instead of
rerunning inspect. Name paired files as `*.params.json` and `*.result.json`.

Without `--out`, default managed inspect output is compact slim JSON evidence. For review, add
`--md` to render the same evidence as Markdown; Markdown is an agent-readable view, not a roundtrip
machine format. Use default JSON or `--json` for small programmatic parsing and ambiguity checks.
Use `univer inspect tools list`/`resolve` text output by default; reserve registry `--json` for
machine-readable diagnostics.

In slim cell facts and value details, `value` uses `cellData.v`/raw readback for typed cell content
and `valueType` prefers `cellData.t` when available; `displayValue` mirrors Facade
`getDisplayValues()`. Inspect tools do not synthesize `value` from display text or agent-oriented
normalization.

Use the evidence ladder selected by the task-local route contract when one exists. Without a local
route owner, small bounded edits usually start
`units -> focused sheet-overview or sheet-search -> focused sheet-range slim -> exact include`.
Large transforms may start with materialized source or TSV orientation, then must confirm with
target-visible custom aggregation or focused managed inspect. Escalate to exact include fields only
for named ambiguities or assertion contracts that depend on display strings, formulas, formats,
styles, or cell model details. Use `sheet-formulas` for formula audits and
`sheet-conditional-formats` for conditional formatting rule resources.

For large tables, do not use `sheet-range` as a table dump. Use source orientation plus
overview/search only to bound the question, then obtain concise source/target facts such as counts,
grouped totals, dedupe facts, mismatches, expected/current shape comparisons, head/tail samples, or
cross-range alignment. If one managed artifact plus bounded shell reads cannot answer that same
bounded aggregation/comparison question, write one small sidecar-local custom inspect script that
returns compact JSON facts instead of dumping every source row or running multiple `sheet-range`
plus `jq` slices. Do not use custom scripts as a universal first step or to replace simple unit,
sheet, search, one-cell, or small-range confirmation reads. Keep the script under the target sidecar
`inspect-scripts/` directory, not under a generic work directory, pass variables through params JSON,
and keep durable workbook changes in SaC migration source.

Handle recoverable inspect diagnostics by narrowing first. If `sheet-range` reports `maxCells`
exceeded, use `sheet-overview` or used-range evidence, then split into smaller target ranges; only
raise `maxCells` deliberately when the broad read is truly required. If inspect reports an
unsupported include or semantic style trait, choose one of the supported include fields/traits in
the diagnostic, or switch to the dedicated managed evidence tool. Do not inspect workbook internals
to recover unsupported style evidence.

When typed values, display strings, formulas, number formats, cell model details, or static style
traits affect the decision, request focused `sheet-range` fields such as `values`,
`displayValues`, `valueDetails`, `cellFacts`, `cellData`, `formulas`, `numberFormats`, or
`semanticStyles`. Use `sheet-conditional-formats` for conditional formatting rule resources;
combine it with value evidence when a value-dependent rule is part of the task.

Read `references/evidence-tools.md` only when inspect params, include fields, custom script shape,
or recoverable inspect diagnostics are unclear.

## SaC Common API Pocket Guide

Use these stable primitives before lookup when the task is ordinary range read/write/format or
assertion work. If a diagnostic names a missing overload, e

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dream-num](https://github.com/dream-num)
- **Source:** [dream-num/skills](https://github.com/dream-num/skills)
- **License:** Apache-2.0
- **Homepage:** https://univer.ai

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dream-num-skills-univer-cli
- Seller: https://agentstack.voostack.com/s/dream-num
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.