How to Perform Bulk Text Updates Using OfficeCLI set Command with --find and --replace Flags

The OfficeCLI set command supports bulk text updates through dedicated --find and --replace flags that locate text patterns across Word, PowerPoint, and Excel documents without requiring custom scripts.

Starting with version 2.0, the iOfficeAI/OfficeCLI repository introduces top-level --find and --replace options as syntactic sugar for the set command, streamlining the process of performing bulk text updates across Office OpenXML documents. These flags merge into the internal --prop array while providing a cleaner CLI syntax and enforcing safety constraints that prevent conflicting inputs.

How the --find and --replace Flags Work

The implementation of bulk text updates follows a strict parsing and execution pipeline defined across several core files in the repository.

Command Parsing and Validation

In CommandBuilder.Set.cs (lines 18-28), the set command defines the --find and --replace options as top-level CLI arguments. When present, these values are merged into the --prop array as "find=<value>" and "replace=<value>" respectively, ensuring downstream handlers in WordHandler.Helpers.FindReplace.cs receive consistent input regardless of which syntax you use.

The parser enforces mutual exclusivity between the new flags and legacy syntax. Lines 55-68 of CommandBuilder.Set.cs explicitly forbid mixing --find with --prop find= or --replace with --prop replace=, emitting a clear error message to prevent ambiguous operations.

Regex Support and Pattern Matching

By default, --find treats values as literal substrings. To enable .NET-compatible regular expressions, prefix your pattern with r" and terminate it with " (e.g., --find r"\d+"). This behavior is documented in AttributeFilter.cs (lines 433-476) and applies consistently across both the query and set commands.

The search operation is case-insensitive by default, matching variations like "draft", "Draft", and "DRAFT" without requiring explicit regex flags.

Practical Examples for Bulk Text Updates

The following commands demonstrate common scenarios for performing bulk text updates using the --find and --replace flags:

# Replace a literal string throughout an entire Word document

officecli set report.docx / --find "draft" --replace "final"

# Regex replacement: standardize all percentage values to 100%

officecli set finances.docx / --find r"\d+%" --replace "100%"

# Target specific XML elements using XPath (e.g., paragraphs only)

officecli set summary.docx //w:p --find "Summary" --replace "Executive Summary"

# Track changes during replacement by specifying revision properties

officecli set proposal.pptx / --find "TODO" --replace "Completed" \
  --prop revision.author=Bob --prop revision.date=2024-10-01

Combining with Other Operations

The --find and --replace flags integrate seamlessly with other property updates and document protections.

Applying Styles After Replacement

You can chain bulk text updates with formatting changes by appending additional --prop arguments. The replacement executes first, followed by the application of styling properties to the matched elements:

officecli set brochure.docx / --find "Important" --replace "Critical" \
  --prop bold=true --prop color=blue

Document Protection Checks

Before executing bulk text updates, the command validates that the target document is not protected. If the document contains editing restrictions, the operation halts unless you provide the --force flag to override the safety check.

Summary

• The set command in OfficeCLI 2.0+ provides first-class --find and --replace flags for bulk text updates across Word, PowerPoint, and Excel files.
• Implementation files include CommandBuilder.Set.cs for parsing, AttributeFilter.cs for regex handling, and WordHandler.Helpers.FindReplace.cs for DOM mutation.
• Regex support requires the r"pattern" syntax, while literal searches are case-insensitive by default.
• Conflict prevention ensures you cannot mix --find with legacy --prop find= syntax.
• Integration capabilities allow combining text replacement with XPath targeting, revision tracking, and property updates like bold or color formatting.

Frequently Asked Questions

Can I use regular expressions with the --find flag?

Yes. Prefix your pattern with r" and end it with " to enable .NET-compatible regular expressions. For example, --find r"\$\d+" matches dollar amounts. This functionality is implemented in AttributeFilter.cs and works across all supported document types.

What happens if I mix --find with the legacy --prop find= syntax?

The command parser in CommandBuilder.Set.cs (lines 55-68) detects this conflict and emits an error message, preventing the operation from executing. You must choose either the new --find and --replace flags or the legacy --prop find= and --prop replace= format, but not both.

Does this work with Excel and PowerPoint files, or only Word?

The --find and --replace flags work across all supported Office formats. While WordHandler.Helpers.FindReplace.cs handles Word documents, the property merging logic in CommandBuilder.Set.cs routes the merged "find" and "replace" properties to the appropriate handlers for Excel and PowerPoint files, enabling consistent bulk text updates across the entire Office suite.

How do I track changes during bulk replacement?

Add revision.author and optionally revision.date properties to your command. When these properties are present, the handlers in WordHandler.Helpers.FindReplace.cs generate revision tracking elements (delete/insert pairs) in the OpenXML DOM, making changes visible as tracked changes in Microsoft Word's "Track Changes" view.

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