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

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 (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. 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:

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:

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:

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):

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.
• 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 (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 (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.

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