Skip to content

excel cell add

Jump to bottom
goworm edited this page Jul 19, 2026 · 56 revisions

Excel: Cell - add

Add cells with values, formulas, and formatting.

Path: /{SheetName}

Properties

Property Default Description
ref / address (auto) Cell reference (e.g., A1). If omitted, auto-assigns next available cell in row 1. Note: path is rejected with a hint to use ref or address.
shift - Cell-level insert direction — right or down (Excel UI's Insert Cells… dialog). Only cellRefs within the affected row/column are updated; for full-band insert with formula refs/CF/DV/hyperlinks/tables adjusted across the whole sheet, use add --type row / add --type col instead.
value Cell value
formula Formula (e.g., =SUM(A1:A10))
type auto string/str, number/num, boolean/bool, date, error (Excel error tokens: #DIV/0!, #N/A, #NAME?, #NULL!, #NUM!, #REF!, #VALUE!)
phonetic string Japanese furigana / CJK ruby reading. Promotes the cell text into the SST, appends a single <rPh> spanning the entire base text, and seeds <phoneticPr> with FullWidthKatakana / Distributed defaults. Get surfaces it as phonetic=.... Multi-segment phonetic runs are out of scope; use raw OOXML for finer slicing.
image file path (v1.0.139+) In-cell image ("Place in Cell" / Excel 365 richValue) — the image becomes the cell's value (formulas reading the cell see a non-blank value), unlike a floating add --type picture which leaves the cell empty. Raster only (SVG rejected). Stored as xl/richData _localImage; down-level Excel shows a #VALUE! fallback, Excel 365 renders the image. Confirmed live: add /Sheet1 --type cell --prop ref=A1 --prop image=photo.png → get reports type=Image, image.contentType, image.fileSize, alt.
image.alt / alt string Alt text for the in-cell image. Only valid alongside image=.
(style keys) See Cell set for style properties

Notes

  • Formula auto-detect: A value starting with = is automatically treated as a formula — no need for a separate formula property. For example, value="=SUM(A1:A10)" works identically to formula="=SUM(A1:A10)".
  • Formula prefix: Leading = sign is automatically stripped from the formula property (e.g., formula="=SUM(A1:A10)" works the same as formula="SUM(A1:A10)").
  • Array formula literal braces rejected: formula='{=SUM(...)}' throws — use the arrayformula=... property instead.
  • Literal value clears stale formula: writing value=... on a cell that previously held a formula clears the cached formula.
  • Boolean normalization: type=boolean converts true/yes/1 to 1, and false/no/0 to 0.
  • Conflicting value + formula: supplying both value= and formula= emits a warning; the formula wins.
  • Cell length limit: values exceeding Excel's 32767-char per-cell limit are rejected.
  • ISO datetime with time: value=2024-01-15T09:30:00 is converted to the OADate serial.
  • Cell-ref path tail: add /Sheet1/A5 --type cell --prop value=... writes to A5 (path tail honored, not just auto-appended to row 1).
  • Dynamic-array functions: Excel 2016+ dynamic-array functions (FILTER, SORT, SORTBY, UNIQUE, SEQUENCE, RANDARRAY, XLOOKUP, etc.) are auto-prefixed with _xlfn. for legacy compatibility.
  • OFFSET / INDIRECT: the calc engine now produces reference values for OFFSET and INDIRECT, so =OFFSET(A1,0,0) resolves rather than returning null. Defined names whose body is a formula (e.g. =OFFSET(...)) are inlined at parse time.
  • Element-wise scalar functions spill over array arguments (v1.0.139+): most single-value functions (text, math, logical/info, date, bitwise, base-conversion, plus CHOOSE/IFERROR/IFNA) now map over every element when given a multi-cell array instead of evaluating only the first — =SUM(LEN(A1:A10)) sums the length of every cell's text, not just A1's. Aggregate/lookup/dynamic-array functions were unaffected either way (they already consumed the whole array themselves).
  • Auto-ref: Adding a cell without ref auto-assigns the next available cell in row 1.

Examples

officecli add data.xlsx /Sheet1 --type cell --prop ref=A1 --prop value="Hello"
officecli add data.xlsx /Sheet1 --type cell --prop ref=B1 --prop formula="=SUM(A1:A10)"
officecli add data.xlsx /Sheet1 --type cell --prop ref=C1 --prop value=100 --prop type=number --prop bold=true --prop fill=FFFF00

Row add

Inserts a row at the specified index. Existing rows at or below the index automatically shift downward. Merge cells, conditional formatting, data validations, AutoFilter references, named ranges, hyperlinks, table refs, and formula references are all rewritten across the sheet (Path A: regex-based). Cell-content shorthand: pass c1=/c2=/c3= to seed values into the inserted row's cells in order.

Property Default Description
cols Number of empty cells to create in the row
c{N} Seed cell content at the {N}th column (e.g. c1=Name --prop c2=Score)

Use --index N to specify insertion position (1-based). Omit to append. --from /Sheet1/row[N] (or --from /Sheet1/col[L]) copies cells from an existing row/col with values, formulas, and styles; formula refs are delta-shifted to match the destination row/col.

officecli add data.xlsx /Sheet1 --type row --index 3
officecli add data.xlsx /Sheet1 --type row --index 3 --prop cols=5
officecli add data.xlsx /Sheet1 --type row --index 5 --from /Sheet1/row[2]
officecli add data.xlsx /Sheet1 --type row --index 6 --prop c1=Alice --prop c2=42

Column add

Inserts a column at the specified position. Existing columns at or after the insert position shift right. Merge cells, named ranges, conditional formatting, data validations, AutoFilter, hyperlinks, table refs, and formula references are all rewritten across the sheet.

Property Default Description
width Column width (characters)

Use --index N (1-based number) or --prop name=C (column letter) to specify the insert position. Both forms are equivalent.

# Insert column at position 3 (shifts existing column C → D)
officecli add data.xlsx /Sheet1 --type col --index 3

# Insert column by letter name
officecli add data.xlsx /Sheet1 --type col --prop name=C

# Insert column with custom width
officecli add data.xlsx /Sheet1 --type col --index 2 --prop width=20

Note: Excel's native path notation (Sheet1!A1, Sheet1!A:A, Sheet1!1:1) is also accepted as an alias for the DOM-style paths (/Sheet1/A1, /Sheet1/col[A], /Sheet1/row[1]). The whole-column / whole-row forms also work directly under a sheet prefix — /Sheet1/B:B and /Sheet1/1:1 (v1.0.129+) resolve the same as /Sheet1/col[B] / /Sheet1/row[1]. A multi-column/row span like /Sheet1/B:C is accepted by set (applies to the whole span) but rejected by get/single-target reads with a message pointing at the single-column form (col[B] … col[C]) instead of a bare parse failure.

Based on OfficeCLI v1.0.139

Clone this wiki locally