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

> Learn to set raw XML content in Office documents with OfficeCLI. Use the raw-set verb and XPath to inject complex OpenXML structures into any document part.

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

---

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

```bash
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.

```bash
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.

```bash
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.

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