# How to Modify Properties of Elements in Office Documents Using OfficeCLI

> Easily modify Office document element properties like text and fonts using the officecli set command. Update Word, Excel, and PowerPoint files programmatically.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-28

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.