How to Set Raw XML Content in Office Documents Using OfficeCLI: A Complete Guide

The raw-set verb in OfficeCLI allows you to inject literal OOXML into specific document parts using XPath selectors, serving as the universal escape hatch when high-level typed verbs cannot express complex OpenXML structures.

OfficeCLI is an open-source command-line interface for manipulating Word, Excel, and PowerPoint files through their underlying OpenXML architecture. When you need to set raw XML content in Office documents using OfficeCLI, the raw-set verb provides low-level access to document parts that bypasses the abstraction layer of high-level semantic commands.

How the raw-set Verb Works Within OfficeCLI

OfficeCLI treats Word, Excel, and PowerPoint files as ZIP archives containing discrete OpenXML parts. While most edits use high-level verbs (add, set, remove) that map to semantic paths like /body/p[1]/r[2], these abstractions cannot expose every OpenXML attribute or custom element. The raw-set verb functions as the direct mutation API.

According to the source code in src/officecli/ResidentServer.cs at line 1136, the raw-set command is dispatched to the ResidentServer as a low-level package mutation. For Word documents specifically, the WordHandler class in src/officecli/Handlers/WordHandler.cs orchestrates these operations, implementing lazy part creation, ID allocation, and batch-deferred serialization to maintain linear performance even with multiple raw-set calls.

The Command Flow for Raw XML Injection

Executing a raw-set operation requires four discrete components that map directly to the underlying OpenXML structure:

1. Select the part – Target specific document components such as document, styles, /slide[1], workbook, or customXml.
2. Provide an XPath – Specify the exact node or element you intend to modify.
3. Choose an action – Use append, prepend, insertbefore, insertafter, replace, remove, or setattr to define the mutation type.
4. Supply the raw XML – Provide the literal OOXML string or attribute/value pair that will be written verbatim into the target location.

The raw-set verb bypasses schema validation entirely, which means you must ensure your injected XML is well-formed and includes correct namespace prefixes—the CLI does not add missing namespaces automatically.

Practical Examples for Setting Raw XML Content

Inject Custom List Items in Word Documents

When working with dropdown controls or list definitions where the display text must differ from the underlying value, typed verbs often fall short. Use raw-set to append list items with explicit value attributes.

FILE="menu.docx"
officecli raw-set "$FILE" /document \
  --xpath "//w:listItem[w:displayText='Engineering']" \
  --action append \
  --xml '<w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Engineering" w:value="ENG"/>'

This command targets the document part within menu.docx, selects the existing list item collection, and appends a new element with the w:value attribute set to "ENG". Note the explicit namespace declaration; raw-set does not inherit default prefixes from the surrounding document context.

Replace PowerPoint Slide Backgrounds with Gradient Fills

To modify slide backgrounds with complex DrawingML elements like gradient fills that the standard set verb cannot express, target specific slide parts using indexed paths.

FILE="presentation.pptx"
officecli raw-set "$FILE" /slide[2] \
  --xpath "//p:bg/p:blipFill" \
  --action replace \
  --xml '<p:blipFill><a:blip r:embed="rId5"/><a:gradFill><a:gs pos="0"><a:srgbClr val="FF0000"/></a:gs><a:gs pos="100000"><a:srgbClr val="00FF00"/></a:gs></a:gradFill></p:blipFill>'

This example replaces the background fill of the second slide with a gradient definition spanning red to green. The /slide[2] part selector directs the operation to the specific slide XML, while the p: and a: namespaces correspond to PresentationML and DrawingML respectively.

Hide Excel Worksheets via Attribute Manipulation

Modify workbook-level attributes, such as sheet visibility states, by targeting the workbook part and using the setattr action.

FILE="budget.xlsx"
officecli raw-set "$FILE" /workbook \
  --xpath "//x:sheet[@name='Forecast']" \
  --action setattr \
  --xml "state=hidden"

Here, the XPath selects the sheet named "Forecast" within the workbook's sheet list, and setattr modifies its state attribute to "hidden" without replacing the entire element. The x: prefix represents the SpreadsheetML namespace required for Excel parts.

Create Custom XML Parts for Metadata

Extend documents with arbitrary XML parts for custom data storage by targeting the /customXml part path.

FILE="report.docx"
officecli raw-set "$FILE" /customXml \
  --xpath "/" \
  --action append \
  --xml '<my:metadata xmlns:my="http://example.com/meta"><my:author>Jane Doe</my:author></my:metadata>'

This creates a new custom XML part in report.docx and appends a fully-custom metadata payload. According to the WordHandler.cs implementation, the system lazily creates the part if it does not exist before applying the raw XML insertion.

Critical Implementation Considerations

Namespace Requirements: Unlike high-level verbs that handle namespace prefixes automatically, raw-set requires you to declare all namespaces within your XML payload. Omitting xmlns:w or other required prefixes will result in malformed documents.

Performance Characteristics: The Word implementation specifically handles raw-set operations through deferred batch serialization. As implemented in src/officecli/Handlers/WordHandler.cs, this ensures that even hundreds of raw-set calls execute in linear time rather than triggering disk I/O for each individual mutation.

Validation Bypass: Because raw-set writes literal XML without schema validation, invalid OpenXML can corrupt the document. Always verify your XML well-formedness before injection.

Summary

• OfficeCLI stores Office documents as OpenXML ZIP archives accessible through the raw-set verb for low-level mutations.
• The ResidentServer (src/officecli/ResidentServer.cs) dispatches raw-set commands, while WordHandler manages Word-specific implementations with lazy part creation and batch serialization.
• You must provide explicit XPath selectors, action types (append, replace, setattr, etc.), and namespace-declared XML to successfully modify document parts.
• raw-set is the only method to inject custom elements like list items with specific values, VML shapes, chart properties, or custom XML parts not exposed by typed verbs.
• The skill documentation in skills/officecli-docx/SKILL.md (line 350) provides the authoritative syntax reference for these operations.

Frequently Asked Questions

What is the difference between the raw and raw-set verbs in OfficeCLI?

The raw verb typically reads or outputs raw XML content from document parts, while raw-set specifically performs write operations—injecting, replacing, or modifying XML nodes. According to plugins/plugin-protocol.md (line 373), raw-set is classified as a mutation command that changes package state, whereas raw commands are generally non-destructive inspection tools.

Does OfficeCLI validate XML before injecting it via raw-set?

No. The raw-set verb performs no schema validation on the XML payload you provide. As noted in the source architecture, the command bypasses validation layers to maximize flexibility, meaning you must ensure your XML is well-formed and schema-compliant. Malformed XML injected through raw-set will corrupt the Office document.

Can I use raw-set to modify any OpenXML part in an Office document?

Yes. raw-set can target any part within the OpenXML package structure, including primary parts like document, workbook, and presentation, as well as secondary parts such as styles, themes, chart, diagramData, and customXml. This universal access makes it the fallback mechanism for any OpenXML element not exposed through typed verbs.

How does OfficeCLI handle performance when making multiple raw-set calls?

The Word implementation specifically optimizes for batch operations through deferred serialization. As implemented in src/officecli/Handlers/WordHandler.cs, the system maintains an in-memory representation of pending changes and performs batch writes to disk, ensuring linear performance scaling even when executing hundreds of raw-set commands against complex documents.

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