Skip to content

word run set

goworm edited this page Jul 8, 2026 · 58 revisions

Word: Run - set

Modify run character formatting, text content, and inline features.

Path: /body/p[N]/r[M]

Properties

Property Accepted Values Description
text text Run text content
font font name Font family
size number (pt) Font size
bold bool Bold
italic bool Italic
color hex color or scheme name Font color. Accepts hex (FF0000/#FF0000) or scheme color names: accent1–accent6, dark1/dark2, light1/light2, text1/text2, background1/background2, hyperlink, followedHyperlink.
font.latin font name Latin font slot (rFonts/@ascii + @hAnsi). See i18n for per-script slots.
font.ea / font.eastasia font name East-Asian font slot (rFonts/@eastAsia) — Chinese/Japanese/Korean
font.cs / font.complexscript font name Complex-script font slot (rFonts/@cs) — Arabic/Hebrew/Thai
font.hint eastAsia / cs / default Font slot hint (rFonts/@hint) — which slot to use for ambiguous CJK characters
font.asciiTheme theme font token Theme font binding for the ascii slot (rFonts/@asciiTheme): minorHAnsi, majorHAnsi, minorEastAsia, majorEastAsia, minorBidi, majorBidi
font.hAnsiTheme theme font token Theme font binding for the hAnsi slot (rFonts/@hAnsiTheme)
font.eaTheme / font.eastAsiaTheme theme font token Theme font binding for the East-Asia slot (rFonts/@eastAsiaTheme): minorEastAsia, majorEastAsia
font.csTheme theme font token Theme font binding for the complex-script slot (rFonts/@cstheme): minorBidi, majorBidi
lang.latin BCP-47 tag (e.g. en-US) Latin language tag (<w:lang w:val>); empty value clears the slot. See i18n.
lang.ea / lang.eastasia BCP-47 tag East-Asian language tag (<w:lang w:eastAsia>)
lang.cs / lang.complexscript BCP-47 tag Complex-script language tag (<w:lang w:bidi>)
bold.cs / font.bold.cs bool Complex-script bold (<w:bCs/>) — required for Arabic/Hebrew bold to render
italic.cs / font.italic.cs bool Complex-script italic (<w:iCs/>)
size.cs / font.size.cs pt Complex-script size (<w:szCs/>)
direction / dir / rtl (alias) rtl / ltr Run-level reading direction; writes <w:rtl/> on rPr
underline OOXML underline enum or aliases Underline. Full enum: none, single, double, thick, dotted, dottedHeavy, dash, dashLong, dashLongHeavy, dashDotHeavy, dashDotDotHeavy, dotDash, dotDotDash, wave (alias wavy), wavyHeavy, wavyDouble, words. Aliases: dashed → dash, dashdot → dotDash.
underline.color hex color Underline color, distinct from the run text color. (Also available on pptx run.)
position half-points (e.g. 4 for +2pt) Baseline offset via <w:position w:val> (ST_SignedHpsMeasure). Distinct from vertAlign=super/sub — keeps full size and offsets by exact half-points.
revision.type ins / del / format / moveFrom / moveTo Track-change creation. ins/del wrap the run in <w:ins>/<w:del>; format writes <w:rPrChange> inside the property block; moveFrom/moveTo emit paired move-range markers. Pair with revision.author / revision.date / revision.id. Bare revision=... is rejected up-front.
revision.action accept / reject Act on existing revisions. Use with the /revision selector — e.g. set <doc> '/revision[@author=Alice]' --prop revision.action=accept. Mixing revision.action with any creation key is rejected as ambiguous intent.
strike bool Strikethrough
highlight color name or hex Highlight
caps / allCaps bool All caps
smallCaps bool Small caps
dstrike bool Double strikethrough
superscript bool Superscript
subscript bool Subscript
vanish bool Hidden text
outline, shadow, emboss, imprint bool Text effects
noProof bool No spell check
rtl bool Right-to-left
charSpacing/letterSpacing/spacing pt (e.g., 2pt) Character spacing
kern half-points (e.g. 28 = 14pt) Kerning activation threshold (<w:kern w:val>): font sizes at/above this get auto pair kerning. Bare integer, no pt suffix; range 0-3277; empty clears.
shading/shd shading format Background
link URL or none Hyperlink
formula LaTeX string Replace with inline math
alt text Alt text (for embedded images)
width, height EMU Image size (embedded images)
path/src file path Replace image file (for runs containing images)
textOutline "WIDTHpt;COLOR" (e.g. "0.5pt;FF0000"), none Text outline (Word 2010+)
textFill "C1;C2[;ANGLE]" (linear gradient), "radial:C1;C2", or solid COLOR Text fill gradient (Word 2010+)
w14shadow "COLOR[;BLUR[;ANGLE[;DIST[;OPACITY]]]]", none Text shadow (Word 2010+)
w14glow "COLOR[;RADIUS[;OPACITY]]", none Text glow (Word 2010+)
w14reflection tight, half/true, full, none Text reflection (Word 2010+)

w14 Text Effects: Separator is ; (preferred) or - (legacy fallback). Use none or false to remove an effect.

Character-offset formatting (range=, v1.0.131+)

Format a character span without addressing an individual run — set it on the paragraph or body path, not on r[N]:

officecli set report.docx /body/p[1] --prop range=6:15 --prop bold=true
officecli set report.docx /body/p[1] --prop range=0:5,16:21 --prop italic=true
  • Value is one or more start:end spans, 0-based and half-open (6:15 bolds characters 6 through 14), colon-separated; multiple disjoint spans are comma-separated and normalized to ascending order.
  • The paragraph scope is carried by the path, not the value: a /body/p[N] path treats offsets as relative to that paragraph's own concatenated run text; a /body path spans every paragraph (offsets are relative to the whole concatenated text). A single span may straddle a paragraph boundary.
  • The offset-based sibling of find= — find locates the span by text (hits every occurrence, ambiguous on repeated text); range locates it by explicit character position. find and range are mutually exclusive on one call.
  • Formatting only — range requires a format property; text=, replace=, and revision.* are rejected alongside it. Out-of-bounds or malformed specs throw.
  • Not available on Excel (a cell has no paragraph/run character axis — intra-cell rich text is set wholesale via runs=json).

Examples

# Change run formatting
officecli set report.docx /body/p[1]/r[1] --prop font=Arial --prop size=14 --prop bold=true --prop color=FF0000

# Add hyperlink to a run
officecli set report.docx /body/p[1]/r[1] --prop link=https://example.com

# Replace an embedded image
officecli set report.docx /body/p[3]/r[1] --prop src=new-logo.png

# Add text outline
officecli set report.docx /body/p[1]/r[1] --prop textOutline="0.5pt;FF0000"

# Add text gradient fill
officecli set report.docx /body/p[1]/r[1] --prop textFill="FF0000;0000FF;90"

# Add text glow
officecli set report.docx /body/p[1]/r[1] --prop w14glow="4472C4;6;50"

# Remove text effects
officecli set report.docx /body/p[1]/r[1] --prop textOutline=none --prop w14shadow=none

Based on OfficeCLI v1.0.131

Clone this wiki locally