How to Modify Properties of Elements in Office Documents Using OfficeCLI

Use the officecli set command with a target file, element selector, and --prop flags to change text, fonts, colors, and positioning across Word, Excel, and PowerPoint documents.

The iOfficeAI/OfficeCLI repository provides a cross-platform command-line interface for programmatic manipulation of Office Open XML documents. Its DOM-layer set command enables precise property modifications through a unified syntax that operates consistently across .docx, .xlsx, and .pptx formats.

Understanding the Three-Layer Architecture

OfficeCLI implements a three-layer architecture (L1 read, L2 DOM, L3 raw XML) where property modifications operate at the L2 DOM layer. This abstraction translates high-level property changes into low-level OOXML mutations while maintaining document integrity. The architecture ensures that whether you are changing a PowerPoint shape color or an Excel cell value, the command interface remains consistent.

The set Command Structure

The set command is constructed by CommandBuilder.BuildSetCommand in src/officecli/CommandBuilder.Set.cs. It uses System.CommandLine to define the following syntax:

Argument	Description
file	Path to the Office document (.docx, .xlsx, .pptx)
path	Data-path or XPath-like selector to the target element
--prop	Key-value pairs (key=value) describing new property values
--find / --replace	Convenience flags for text substitution workflows
--force	Bypasses protection checks for protected Word documents

Argument Normalization

Before mutation occurs, the command normalizes input arguments. In CommandBuilder.Set.cs lines 38-44, the parser detects bare key=value arguments missing the --prop flag and emits warnings. Lines 47-55 merge --find and --replace values into the properties array for backward compatibility, converting them to find= and replace= property entries.

The Property Modification Pipeline

When executed, the set command follows a strict mutation pipeline orchestrated in CommandBuilder.Set.cs:

1. Document Handler Creation: DocumentHandlerFactory.Open() instantiates format-specific handlers (WordHandler, ExcelHandler, or PowerPointHandler) based on the file extension.

2. Protection Validation: For Word documents, the system checks for document protection unless --force is specified or the operation modifies protection properties (lines 29-34).

3. Property Application: ApplySetWithCorrection() applies parsed properties, auto-corrects misspelled keys, and separates supported from unsupported attributes (lines 42-44).

4. Response Generation: The command emits structured output containing applied changes, match counts, and warnings. When --json is used, warnings are formatted as CliWarning objects for programmatic consumption (lines 107-120).

Working with Element Selectors

OfficeCLI supports multiple selector syntaxes depending on document type:

• XPath-like paths: /slide[1]/shape[2] for PowerPoint or /body/p[3]/r[1] for Word paragraphs
• Excel-native selectors: Sheet1!A1 for cells or Sheet1!row[Salary>5000] for bulk row operations

Practical Code Examples

# Modify text and color in a PowerPoint shape

officecli set deck.pptx '/slide[1]/shape[1]' --prop text="Quarterly Revenue" --prop color=FF0000

# Change font properties in a Word paragraph

officecli set report.docx /body/p[3]/r[1] --prop size=14pt --prop bold=true

# Bulk update Excel rows matching criteria

officecli set data.xlsx 'Sheet1!row[Region=EMEA]' --prop fill=yellow

# Use convenience flags for text replacement

officecli set deck.pptx '/slide[2]/shape[3]' --find "Old Title" --replace "New Title"

# AI-friendly JSON output with structured warnings

officecli set report.docx /body/p[5] --prop text="Executive Summary" --json

Advanced Features and Edge Cases

The selected Pseudo-Path

For interactive workflows, the set command supports a deprecated selected pseudo-path that resolves the current selection from a running watch process. The system queries WatchNotifier.QuerySelection and processes each selected path individually (lines 101-112).

Document Protection Handling

When modifying Word documents, OfficeCLI validates protection status before mutation. The protection check can be bypassed using the --force flag or when the operation itself modifies document protection settings.

Batch Processing Integration

The property modification logic integrates with the batch command, reusing the same DocumentHandler interface to process multiple modifications efficiently across document sets without reopening files.

Summary

• The set command in CommandBuilder.Set.cs provides the primary interface for modifying Office document properties
• System.CommandLine parses arguments including --prop key-value pairs and convenience flags
• DocumentHandlerFactory creates format-specific handlers that implement the actual OOXML mutations
• The pipeline includes auto-correction of property keys and validation of document protection
• JSON output mode emits structured CliWarning objects for programmatic consumption by AI agents

Frequently Asked Questions

What file formats does the set command support?

The set command supports Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) documents through dedicated handlers in the src/officecli/Handlers/ directory. Each handler implements format-specific logic for applying property changes while maintaining OOXML schema compliance.

How does OfficeCLI handle invalid or misspelled property keys?

During execution, ApplySetWithCorrection() automatically corrects common misspellings of property keys and returns warnings for unsupported properties. The command applies valid properties while reporting auto-corrections and unsupported keys in the response output.

Can I modify protected Word documents?

Yes, but only when using the --force flag or when the property modification itself changes document protection settings. By default, OfficeCLI checks for document protection in CommandBuilder.Set.cs (lines 29-34) and prevents accidental modifications to protected content.

What is the difference between using --prop and --find/--replace?

The --prop flag accepts any valid property key-value pair for comprehensive modifications. The --find and --replace flags are convenience shortcuts that the CLI automatically converts to --prop find="value" --prop replace="value" during argument normalization, specifically designed for text substitution workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}