Skip to content

command set

Jump to bottom
goworm edited this page Jul 17, 2026 · 53 revisions

set

Modify properties of a document element.

Synopsis

officecli set <file> <path> [--find <text>] [--replace <text>] --prop <key=value> [--prop ...]

Description

Modifies one or more properties of the element at the specified path. Multiple properties can be set by repeating --prop. Reports which properties were applied and which were unsupported.

Arguments

Name Type Required Default Description
file FileInfo Yes - Office document path
path string Yes - DOM path, selector (e.g. paragraph[style=Heading1], Sheet1!row[Salary>5000]), Excel-native path (Sheet1!A1), or selected for watch-preview selection. Bare unscoped selectors (no element or / prefix) are rejected for agent safety.

Options

Name Type Required Default Description
--prop string (repeatable) Yes (unless --find alone) - Property in key=value format
--find string No - Case-insensitive text/value filter — promoted from the legacy --prop find=X form. Combining --find with --prop find=... is rejected as ambiguous.
--replace string No - Replacement text — promoted from --prop replace=X to a top-level flag. Use with --find.

Output: normalization echo (v1.0.137+)

The receipt appends (applied: ...) when the canonical stored form differs from what you typed — so a caller that verifies its own write doesn't mistake a lenient-input normalization for a failed edit:

officecli set report.docx /body/p[1]/r[1] --prop font=仿宋
# Updated /body/p[1]/r[1]: font=仿宋 (applied: font.ea=仿宋, font.latin=仿宋)

officecli set data.xlsx /Sheet1/A1 --prop color=red
# Updated /Sheet1/A1: color=red (applied: color=#FF0000)

officecli set report.docx /body/p[1]/r[1] --prop size=14
# Updated /body/p[1]/r[1]: size=14 (applied: size=14pt)

The suffix only appears when the stored form diverges from the request — a write-read-identical set keeps the plain Updated <path>: k=v receipt unchanged. Same behavior in text and --json output, one-shot and resident. Selector paths and unresolvable paths skip the echo.

Format-Specific References

Notes

  • Property keys are case-insensitive.
  • Boolean values: true/1/yes (truthy), false/0/no/empty (falsy).
  • Color values: hex RGB without # prefix (e.g., FF0000).
  • Dimensions: EMU or with unit suffix (cm, in, pt, px).
  • Query-selector paths (all formats): Selectors target elements by attribute and now flow through the same engine as query — set <doc> 'paragraph[style=Heading1]' --prop font=Arial, set <doc> 'Sheet1!row[Salary>5000]' --prop fill=FFFF00. Excel-native paths (Sheet1!A1) are accepted alongside the /Sheet1/A1 form. Selector mutation throws on attribute predicates the handler doesn't support, rather than silently no-oping.
  • Boolean and / or in selectors: cell[value>5000 or value<100], cell[(type=Number or type=Date) and value>0]. query, set, and remove all share the same boolean engine across all three formats. Row-by-column-name filters like row[Salary>5000] are supported in Excel; OR'd table-column predicates inside row[…] fail loud (never silent).
  • --find / --replace flags: Top-level text/value filter and replacement. The legacy --prop find=X --prop replace=Y form still works but emits a stderr hint pointing at the new flags. On docx, set --find … --replace … --prop revision.author=… performs a tracked Find&Replace.
  • Auto-create styles (Word): Setting properties on a non-existent /styles/{StyleId} path automatically creates the style.
  • Selected pseudo-path: When a watch process is running, officecli set <file> selected --prop ... applies the property set to each currently-selected element. Click or rubber-band in the browser preview to select.

See Also

Based on OfficeCLI v1.0.137

Clone this wiki locally