# Overview

`run` is the workbook-local programmable surface in `univer-cli`. It executes a bounded JavaScript function inside the Univer spreadsheet engine so you can read workbook state, compute results, and write workbook state.

Read this topic first when the job belongs in `run` but you have not chosen the exact API yet.

## When To Use `run`

Use `run` when the task is workbook-local logic that is clearer or more reliable in API form, especially for:

- styling and presentation
- row or column structure changes
- row or column outline groups
- freeze panes, gridline settings, and sheet-level display settings
- merge or unmerge flows
- formula orchestration that needs workbook-native recalculation
- chart creation, readback, and source range maintenance
- shape creation, connector linking, readback, and maintenance
- outline group creation, readback, collapse or expand, remove, and clear workflows
- bounded read/compute/write logic inside one workbook

Prefer smaller surfaces when they already express the task directly:

- `inspect` for reconnaissance and workbook-visible verification
- `search` to locate rows, columns, sheets, and formula matches
- `pipe out` / `pipe in` for bulk rectangular data roundtrips through shell tools

## Quick Start

Use this command shape. The script must be an arrow function and should return a plain object.

```bash
univer run <univer-path> --code '() => {
  const workbook = univerAPI.getActiveWorkbook();
  const sheet = workbook.getSheetByName("Sheet1");
  if (!sheet) return { success: false, error: "Sheet1 not found" };

  sheet.getRange("A1").setValue("ready");
  return { success: true, value: sheet.getRange("A1").getValue() };
}'
```

Use one of these wrappers:

- `() => {}`
- `async () => {}`

## Hard Rules

- always wrap the program in an arrow function
- always return an object
- use only APIs documented in this run manual reference family
- strictly use documented methods; do not guess or invent API names
- prefer A1 notation for fixed ranges
- remember that coordinate overloads are 0-based
- check for missing sheets before writing
- keep the operation bounded to the workbook task at hand
- verify the result with workbook-visible reads after the command

If a needed API is not documented here, stop and inspect or update the run manual documentation instead of guessing method names, overloads, enum names, or object relationships.

## Common Task Aliases

- `autofill` -> `ranges`
- `fill-series` -> `ranges`
- `get-values` -> `ranges`
- `read-range` -> `ranges`
- `formula-readback` -> `formulas`
- `calculation` -> `formulas`
- `freeze-panes` -> `sheets`
- `number-format` -> `formatting`
- `conditional-format` -> `conditional-formatting`
- `condition-format` -> `conditional-formatting`
- `color-scale` -> `conditional-formatting`
- `data-bar` -> `conditional-formatting`
- `icon-set` -> `conditional-formatting`
- `chart` -> `charts`
- `insert-chart` -> `charts`
- `chart-builder` -> `charts`
- `shape` -> `shapes`
- `insert-shape` -> `shapes`
- `connector-shape` -> `shapes`
- `connect-shapes` -> `shapes`
- `outline` -> `outlines`
- `row-outline` -> `outlines`
- `column-outline` -> `outlines`
- `group-rows` -> `outlines`
- `group-columns` -> `outlines`

## Topics

- `overview` - command selection, hard rules, and progressive discovery
- `core` - `univerAPI`, workbook access, worksheet access, `getRange()`, A1 notation, coordinates
- `ranges` - value reads, writes, shape rules, formulas, merges, clear, cell shifts, AutoFill
- `formulas` - formula writes, async calculation waits, and stale-readback getchas
- `sheets` - worksheet creation, rename, row or column structure, freezing, gridlines, and visibility
- `formatting` - font, fill, alignment, border, number-format, and clear-format APIs
- `conditional-formatting` - rule builders, range binding, worksheet rule lists, color scales, data bars, and icon sets
- `charts` - chart builders, source ranges, readback, update or remove, and viewer rendering notes
- `shapes` - shape builders, connectors, connection sites, readback, update or remove, and viewer rendering notes
- `images` - floating image builders, source positioning, readback, update or delete, and viewer rendering notes
- `hyperlinks` - URL, sheet, range, defined-name links, readback, update, cancel, and parse APIs
- `defined-names` - workbook and worksheet scoped defined names, builders, update, delete, and hyperlink interop
- `outlines` - row and column groups, readback, collapse or expand, remove, and clear APIs

## Formula Readback Warning

Formula calculation is asynchronous. If you set a formula with `setFormula()` or by writing a string starting with `=`, do not read the computed result immediately. Wait for calculation to finish:

```javascript
await univerAPI.getFormula().onCalculationResultApplied();
```

Without that wait, readback can be stale.

## Related Topics

- See `core` for workbook, sheet, structure, coordinates, and `getRange()`.
- See `ranges` for range reads and writes, formulas, merges, clear, cell insertion and deletion, and AutoFill.
- See `formatting` for fonts, fills, alignment, borders, and number formats.
- See `conditional-formatting` for worksheet-level rules that format cells based on values, text, formulas, scales, bars, or icon sets.
- See `charts` for worksheet chart builders, facade readback, and view-host rendering checks.
- See `shapes` for worksheet shape builders, connector links, facade readback, and view-host rendering checks.
- See `outlines` for row or column grouping, collapse or expand, remove, and clear workflows.
