dream-num/univer-cli/base

Base units

Model

A Base is one Unit inside a .univer file:

FUniver
└── FBase
    └── FBaseTable
        ├── FBaseTableField   schema and value contract
        ├── FBaseTableRecord  stored business data
        └── FBaseTableView    projection of the same table records

• Resolve FBase by Unit ID. Tables own their fields, records, and views; views only add filter,

sort, group, visibility, and type-specific presentation.

• The primary field is the record's visible identity for links, cards, and details. Define it with

insertTable(..., { primaryFieldName }) instead of adding a duplicate label field.

• Use stable Unit/Table/Field/Record/View IDs in Facade relationships and user-facing names for

display. Record values and view config normally refer to Field IDs.

• table.getFormulaName() is only the structured-reference name for formulas; it may differ from

the table's display name.

Entry

The CLI owns Unit and Worktree lifecycle; the Facade owns Base content:

univer unit add data.univer --worktree <worktree-id> --type base --name "CRM" --json
univer inspect base data.univer --worktree <worktree-id> --unit <base-unit-id> --json
univer execute data.univer --worktree <worktree-id> --unit <base-unit-id> -e '…'

execute predefines univerAPI, api, and the FBase named base for the selected Unit. Use base directly; these bindings are reserved and must not be redeclared.

Do not call createBase() after unit add just to obtain a handle. A new Base already contains Table 1 with a primary Name field and Grid; insertTable() also creates a Grid. Run inspect base first, then deliberately reuse, rename, or delete defaults.

Exact API

univer api show FUniver.getBase FBase FBaseTable FBaseTableField FBaseTableRecord FBaseTableView
univer api show FEnum.BaseFieldType FBase.insertTable FBaseTable.addField FBaseTable.addRecords FBaseTable.createView
univer api show IGridViewConfig ICalendarViewConfig IGalleryViewConfig IGanttViewConfig IKanbanViewConfig ICardLayoutConfig

Use focused discovery such as univer api find recordLink --unit base. Follow every referenced child type: if a result says card?: ICardLayoutConfig, run api show ICardLayoutConfig instead of guessing its shape.

Core contracts

• Add fields one at a time with FBaseTable.addField(...); there is no addFields method.
• Single/MultiSelect options use { id, name, color? }; records store option IDs, not labels.
• Progress values follow its configured range: with { start: 0, end: 100 }, 75% is 75, not

0.75.

• Money uses BaseFieldType.Currency and numeric values; Number is not a semantic substitute.
• RecordLink config targets a Table ID and stores target Record IDs. Prefer its dedicated Facade

methods when editing links.

• View config uses Field IDs. Kanban/Gallery card title and fields follow ICardLayoutConfig;

fieldSettings does not replace the card contract.

Verify

After the last write, check:

1. univer inspect base ... --json for tables, primary fields, field types and config, record counts,

and view types. It is read-only and accepts no selector.

1. In a read-only execute, explicitly return record values plus view.getConfig() /

view.getProjection() for stored IDs and view bindings.

1. The rendered required views for blank labels, exposed IDs, implausible dates/percentages, missing

card fields, and empty defaults.

univer screenshot data.univer --worktree <worktree-id> --unit <base-unit-id> --out ./shots

The Base screenshot is ./shots/view.png; it does not accept Sheet ranges or Slide selectors.

For Formula fields, run univer skills get base --full and follow references/formulas.md.