# How to Use OfficeCLI Find and Replace with the `set` Command

> Master OfficeCLI find and replace using the set command. Easily substitute text or modify formatting in Word docs without altering content. Learn how now.

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

---

**Use the `officecli set` command with `--find` and `--replace` flags to perform text substitution in Word documents, or combine `--find` with formatting properties to modify matched text without changing content.**

The iOfficeAI/OfficeCLI repository provides a robust command-line interface for document automation, with the `set` verb serving as the central mutation entry point for Word documents. Mastering the **OfficeCLI find and replace** functionality allows you to perform precise text substitutions, apply conditional formatting, and generate tracked changes through a unified pipeline that processes flags, validates constraints, and dispatches to specialized handlers.

## Understanding the `set` Command Architecture

The implementation of find and replace follows a three-stage pipeline defined in the source code, ensuring safe and predictable document mutations.

### Flag Parsing and Deprecation Handling

In [`src/officecli/CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs) (lines 18-70), the `CommandBuilder.BuildSetCommand` method defines `--find` and `--replace` as top-level options. When you supply these flags, the system merges them into the internal `--prop` array as `find=…` and `replace=…` key-value pairs. While the older `--prop find=` and `--prop replace=` syntax remains functional for backward compatibility, using it triggers a deprecation hint (lines 70-77), making the top-level flags the canonical approach.

### Validation and Safety Checks

Before dispatching to the handler, the command enforces mutual-exclusion constraints (lines 49-72 in the same file). The system prevents combining `find` operations with incompatible keys such as `revision.action` or `range` selectors. Additionally, the `MutationSelectorGuard.EnsureScoped` check ensures that find operations target scoped selectors rather than entire documents, preventing unintended global mutations.

### Dispatch to the Document Handler

After validation, control passes to `WordHandler.Set` in [`src/officecli/Handlers/Word/WordHandler.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.Set.cs). At lines 27-34, the handler detects the presence of a `find` key and routes execution to the **Unified Find** path. This method partitions supplied properties into three buckets—`formatProps`, `paraProps`, and `revisionProps`—then passes the `find` value and optional `replace` value to the `ProcessFind` method, which executes the actual text search, replacement, and optional revision tracking.

## OfficeCLI Find and Replace Syntax Patterns

The `set` command supports multiple interaction patterns, from simple text substitution to complex regex-based transformations with tracked changes.

### Basic Literal Replacement

Use the `--find` and `--replace` flags to substitute specific text within a scoped selector:

```bash
officecli set contract.docx /body/p[3] \
  --find "Acme Corp" \
  --replace "Globex Ltd"

```

This command locates the exact text "Acme Corp" in paragraph 3 and replaces it with "Globex Ltd".

### Regular Expression Matching

Enable pattern matching by prefixing the find string with `r"` or using the `--regex` flag. The `CONSISTENCY(find-regex)` rule in the source code ensures proper regex handling:

```bash
officecli set report.docx /body \
  --find r"\b\d{4}-\d{2}-\d{2}\b" \
  --replace "2025-12-31"

```

This example matches ISO date formats throughout the document body using .NET regular expression syntax.

### Formatting Without Replacement

Combine `--find` with formatting properties to modify text appearance without changing content:

```bash
officecli set résumé.docx /body/p \
  --find "Bachelor of Science" \
  --prop bold=true \
  --prop color=blue

```

The `ProcessFind` method applies `formatProps` (bold and color) to each matched occurrence while preserving the original text.

### Tracked Changes and Metadata

When supplying a `replace` value alongside revision properties, the system creates tracked insertion and deletion markers (`w:ins`/`w:del`):

```bash
officecli set proposal.docx /body \
  --find "Q1 2024" \
  --replace "Q1 2025" \
  --prop revision.type=ins \
  --prop revision.author=alice

```

This creates a tracked change recording Alice as the author of the date modification.

## Summary

- The `set` command in iOfficeAI/OfficeCLI provides a unified mutation interface for find-and-replace operations through the `--find` and `--replace` flags.
- The canonical syntax uses top-level flags rather than the deprecated `--prop find=` approach, with validation occurring in [`src/officecli/CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs).
- The `WordHandler.Set` implementation processes find operations through the `ProcessFind` method, supporting literal text, regex patterns, and formatting-only mutations.
- Safety checks prevent combining find operations with incompatible selectors like `range` or `revision.action`.
- Tracked changes are supported by combining replacement values with revision metadata properties.

## Frequently Asked Questions

### Can I use regular expressions with OfficeCLI find and replace?

Yes. Prefix your find string with `r"` (for example, `r"\d+"`) or include the `--regex` flag to enable .NET regular expression matching. The engine validates this through the `CONSISTENCY(find-regex)` rule before executing the search.

### What is the difference between `--find` and `--prop find=` syntax?

The `--find` and `--replace` flags represent the canonical, recommended syntax introduced in recent versions. The `--prop find=` and `--prop replace=` syntax remains functional for backward compatibility but triggers deprecation warnings in [`src/officecli/CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs) (lines 70-77). Both approaches ultimately merge into the same internal property array.

### Can I combine find/replace with other formatting changes?

Yes. The `WordHandler.Set` method splits properties into `formatProps`, `paraProps`, and `revisionProps` buckets. You can combine `--find` with formatting properties like `--prop bold=true` to apply styling to matched text, or combine `--find` and `--replace` with revision metadata to track changes.

### Why does my command fail when using `range` or `revision.action` with `--find`?

The validation logic in [`src/officecli/CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs) (lines 49-72) enforces mutual exclusion between find operations and certain incompatible keys. You cannot combine `find` with `range` selectors or `revision.action` properties because these represent conflicting mutation strategies. Ensure your selector is scoped properly using `MutationSelectorGuard.EnsureScoped` rather than range-based selection.