OfficeCLI is a command-line tool for reading, creating, and modifying Office documents (.docx, .xlsx, .pptx) using a DOM-like path system. It operates on OpenXML format files without requiring Microsoft Office.

All commands with --json return a unified envelope format:

Success:

{ "success": true, "data": { ... }, "warnings": [...] }

Success (text result):

{ "success": true, "message": "Updated /slide[1]/shape[1]: bold=true" }

Error:

{
  "success": false,
  "error": {
    "error": "Slide 50 not found (total: 8)",
    "code": "not_found",
    "suggestion": "Valid Slide index range: 1-8",
    "validValues": null
  }
}

Error codes: not_found, invalid_value, unsupported_property, invalid_path, unsupported_type, missing_property, file_not_found, file_locked, invalid_selector

officecli config log true    # Enable command logging
officecli config log false   # Disable command logging

OfficeCLI has a built-in help system that loads content directly from the wiki. Navigate from broad overview to specific property detail:

# Layer 1: All elements for a format+verb
officecli pptx set

# Layer 2: One element in detail
officecli pptx set shape

# Layer 3: Specific property format and examples
officecli pptx set shape.fill

Replace pptx with docx or xlsx. Commands: view, get, query, set, add, raw.

When opening a file fails due to an unsupported XML encoding declaration (e.g., files created by python-pptx with encoding="ascii"), OfficeCLI automatically rewrites all XML declarations to encoding="UTF-8" and retries. No manual intervention is required.

When a property name is misspelled by exactly 1 character (Levenshtein distance 1), OfficeCLI auto-corrects it and issues a warning:

Auto-corrected 'valu' to 'value'

Additionally, bare key=value arguments (without --prop) are detected and flagged:

Bare property 'text=Hello' ignored. Did you mean: --prop text=Hello

Import CSV/TSV data into an Excel sheet:

officecli add data.xlsx /Sheet1 --type csv --prop data="Name,Age\nAlice,30\nBob,25" --prop hasHeader=true --prop startCell=A1

• Auto-detects data types: numbers, dates (ISO 8601), booleans, formulas
• hasHeader=true: sets AutoFilter on header row and freezes pane below
• Delimiter: comma (default), or tab for TSV

OfficeCLI performs a daily background version check (at most once per 24 hours). If a newer version is available, a notification is displayed after command output. The check is non-blocking and does not affect command execution. Update info is cached locally.

Each command opens the document, performs the operation, and saves (if modified). Simple but involves file I/O per command.

Use open to start a background process that keeps the document in memory. Subsequent commands communicate via named pipes with near-zero latency. Use close to save and stop. Ideal for multi-step workflows.

officecli open report.docx
officecli view report.docx text
officecli set report.docx /body/p[1] --prop bold=true
officecli close report.docx

Execute multiple commands in a single open/save cycle via JSON input. Best for applying many changes atomically.

officecli batch report.docx --input commands.json

OfficeCLI uses a DOM-like path system to address document elements. Paths are hierarchical with 1-based indexing (XPath convention).

See format-specific references: Word, Excel, PowerPoint.

OfficeCLI accepts dimensions with unit suffixes. Without a suffix, values are interpreted as EMU (English Metric Units).

Example: --prop width=2.54cm is equivalent to --prop width=914400

Negative values are accepted for position properties (x, y, left, top) to place elements outside slide boundaries or to the left/above the slide origin.

Word document properties like indents, margins, and spacing use twips (1/20th of a point). 1 inch = 1440 twips.

• Hex RGB: #FF0000 (red), #00FF00 (green)
• Theme colors (PowerPoint): accent1-accent6, dk1, dk2, lt1, lt2, tx1, tx2, bg1, bg2, hlink, folhlink
• Named colors (Word highlight): yellow, green, cyan, magenta, blue, red, darkBlue, darkCyan, darkGreen, darkMagenta, darkRed, darkYellow, darkGray, lightGray, black

Truthy: true, 1, yes Falsy: false, 0, no, "" (empty string)

• Path indices are 1-based: /body/p[3] = third paragraph (XPath convention)
• --index parameter is 0-based: --index 0 = first position (array convention)

The set and add commands use --prop key=value pairs. Property keys are case-insensitive.

See format-specific references: Word, Excel, PowerPoint.

All hex color values now include the # prefix: #FF0000 (was FF0000).

• Gradient format: gradient;#C1;#C2;angle or linear;#C1;#C2;angle
• Scheme colors (accent1) and special values (none, auto) are unchanged

Colors accept multiple formats:

• Hex: FF0000, #FF0000, F00 (3-char shorthand)
• Named colors: red, green, blue, white, black, yellow, cyan, magenta, orange, purple, pink, brown, gray/grey, silver, gold, navy, teal, maroon, olive, lime, coral, salmon, tomato, crimson, indigo, violet, turquoise, tan, khaki, beige, ivory, lavender, plum, orchid, chocolate, sienna, peru, wheat, linen, skyblue, steelblue, slategray, darkred, darkgreen, darkblue, darkcyan, darkmagenta, darkorange, darkviolet, deeppink, deepskyblue, lightgray, lightgreen, lightblue, lightyellow, lightpink, lightcoral, darkgray, dimgray
• RGB function: rgb(255,0,0) (components 0-255)

#FF0000 matches FF0000 (prefix is normalized for comparison).

All spacing values include a unit suffix:

• spaceBefore / spaceAfter: 12pt (was raw internal values)
• lineSpacing: 1.5x (multiplier) or 18pt (fixed)

Accepts unit-qualified strings:

• spaceBefore / spaceAfter: 12pt, 0.5cm, 0.5in, bare number (backward compatible)
• lineSpacing: 1.5x (multiplier), 150% (= 1.5x), 18pt (fixed), 0.5cm / 0.5in (fixed), bare number (backward compatible)

OfficeCLI provides built-in help for each format:

officecli docx [view|get|query|set|add|raw]
officecli xlsx [view|get|query|set|add|raw]
officecli pptx [view|get|query|set|add|raw]

Based on OfficeCLI v1.0.29