univer-cli

univer is a spreadsheet engine in the terminal. Use it when an agent needs real workbook semantics: sheets, ranges, formulas, formatting, layout, previews, imports, exports, or versioned workbook state.

Install the CLI with npm i -g univer-cli. Update the CLI with univer update. The executable is univer; unv may be available as a short alias.

Core Mental Model

Treat workbook-visible state as the source of truth. A successful command summary, package metadata, or an internal manifest does not prove that sheet names, cell values, formulas, formatting, or exported handoff files are correct.

The workbook path is the local identity. Pick one explicit path such as ./budget.univer and use that path as the CLI target. Do not target workbooks by unitId, sessionId, manifest ids, or runtime ids.

.univer and .unv files are CLI operation targets, not agent-editable data stores. Read and write workbook data through public CLI surfaces such as inspect, search, pipe, run, export, status, and commit.

Use univer help and univer help <command...> for exact syntax. For run scripts, use univer help run and univer help run <topic> before relying on unfamiliar APIs.

Use When

Use this skill when the task involves spreadsheet or workbook work, especially:

• creating, importing, exporting, or handing off .xlsx, .csv, .univer, or .unv files
• inspecting workbook shape, sheets, ranges, formulas, formatting, or visible cell state
• locating content-defined rows, columns, headers, or cells before editing
• making bounded edits to cells, formulas, formatting, charts, shapes, floating images, layout, or sheet structure
• streaming rectangular workbook data through shell tools before reading it into context
• writing generated matrix data back into a sheet-qualified range
• previewing workbook state locally with univer view
• reading submitted local viewer review comments with univer view comments
• creating, restoring, resetting, pulling, or syncing local workbook changesets
• proving that a workbook-visible mutation or export is correct enough to hand back

Default Operating Loop

1. Pick one explicit workbook path, for example ./budget.univer.
2. Create or import a workbook first if no .univer or .unv target exists.
3. Inspect workbook-visible state before deciding where to write.
4. Locate targets from visible headers, values, formulas, or inspected ranges.
5. Choose the smallest public CLI surface that fits the task.
6. Mutate through the CLI, not by editing package internals.
7. Verify changed workbook-visible state with inspect, pipe out, or another public read.
8. Export only after verification when the user needs a handoff file.
9. After changes have been verified, if the user may need to inspect, audit, or review the final workbook, check the current agent tool surface first. If a browser tool is available, run univer view "$WB" --no-open --json, open the returned URL with that browser tool, and include the URL in your response. If no browser tool is available, run univer view "$WB" --open --json; --open uses the OS browser opener, and the CLI returns a prepared URL and diagnostic if the browser cannot be opened automatically.
10. Commit or sync only after verified changes when versioning is part of the workflow.

Hard Rules

• Do not read .univer or .unv internals to infer workbook contents.
• Do not write, patch, unzip, rezip, rename internal files, or manipulate workbook package contents.
• Do not inspect manifest.json, snapshots, mutation logs, or package fragments as a substitute for workbook-visible reads.
• Do not guess sheet names, row numbers, formulas, ranges, or changed cells from memory or file metadata.
• Do not treat stdout summaries as proof of workbook state. Verify with a workbook-visible read.
• Do not invent commands or run APIs. Check univer help and documented run topics.

Direct package access can corrupt workbooks or teach the agent false state. If the CLI cannot read what you need, diagnose the CLI/runtime path instead of bypassing it.

Command Selection

Use canonical command help such as univer help inspect range and univer help pipe out. Top-level help group headings are visual sections only; do not run group-prefixed topics such as univer help read inspect range.

Execution Results

Treat non-zero exit as failure even when stdout is partially present. Read stderr before changing approach; it usually contains the stable diagnostic code, usage, and retry examples.

Keep data stdout clean in shell pipelines. If diagnostics are needed, capture stderr separately so downstream tools receive only workbook data.

univer inspect range "$WB" --range 'Sheet1!A1:D20' > ./range.md 2> ./range.err
status=$?
if [ "$status" -ne 0 ]; then
  sed -n '1,80p' ./range.err
  exit "$status"
fi
sed -n '1,40p' ./range.md

Workflow Recipes

These are verified command shapes. Replace paths, sheet names, and ranges with inspected workbook facts.

Create Or Import, Then Inspect

WB=./orders.univer
univer import ./orders.csv "$WB" --json
univer inspect workbook "$WB"
univer inspect range "$WB" --range 'Sheet1!A1:D4'

Use new when the task starts from a blank workbook:

WB=./workbook.univer
univer new "$WB" --name "Workbook"
univer inspect workbook "$WB"

Locate Before Editing

Use search before editing when the target is defined by visible workbook content:

univer search "$WB" West

Plain text output is one A1 reference per matched cell, which keeps shell pipelines clean. With no matches, stdout is empty and the command still succeeds. Use --json when you need match metadata, the matched cell data preview, truncation flags, counts, or the searched scope:

univer search "$WB" West --sheet Orders --range 'A1:Z200' --json

By default, search checks displayValue, so formatted values such as dates are searchable by the sa