How to Use OfficeCLI `move` and `swap` Commands for Reorganizing Document Content

OfficeCLI provides move and swap commands that let you reorder paragraphs, tables, charts, and slides in Word, Excel, and PowerPoint documents without opening the native Office UI, using selector-based targeting and real-time SSE synchronization.

The iOfficeAI/OfficeCLI repository offers a command-line interface for manipulating Office documents through a selector-positional model. These two commands form the core of its document reorganization capabilities, translating CLI instructions into XML patches that rearrange content elements while maintaining document integrity.

Understanding the Selector-Positional Model

OfficeCLI addresses document elements using selectors that resolve to concrete DOM nodes. This grammar supports:

• p[n] – the nth paragraph
• table[n] – the nth table
• slide[n] – the nth slide (PowerPoint)
• chart[n] – the nth chart on a slide
• sheet[name] – worksheet by name (Excel)

Selectors combine with path separators (/) to target nested elements, such as slide[2]/chart[3].

Using the move Command

Command Syntax and Selectors

The move command relocates a single element to a new index within the document structure.

# Move the 5th paragraph to become the 2nd paragraph in Word

officecli move mydoc.docx "p[5]" "p[2]"

# Move a chart from slide 3 to slide 1 in PowerPoint

officecli move presentation.pptx "slide[3]/chart[1]" "slide[1]"

Internal Implementation

When you execute move, the CLI invokes the handler in src/officecli/Resources/watch-overlay.js around line 296. This builds a patch of type move and transmits it to the server. The server-side SelectorPositionalIndex helper (src/officecli/Core/SelectorPositionalIndex.cs) calculates the new positional index and rewrites the underlying document XML. After server processing, the SSE listener in src/officecli/Resources/watch-sse-core.js receives the patch.op === 'move' event and updates the DOM to maintain UI synchronization.

Using the swap Command

Exchanging Element Positions

The swap command exchanges the positions of two elements directly.

# Swap two tables inside a Word file

officecli swap mydoc.docx "table[1]" "table[3]"

# Swap two worksheets inside an Excel workbook

officecli swap report.xlsx "sheet[Finance]" "sheet[Summary]"

Pipeline Architecture

Like move, the swap command generates a patch in watch-overlay.js, but with patch.op === 'swap'. The server processes this through SelectorPositionalIndex.cs to modify the XML structure. The SSE core then publishes the swap event, which the overlay code consumes to update the DOM without requiring a full page refresh.

Validation and Error Handling

Before executing either command, OfficeCLI runs validation through src/officecli/Handlers/WordHandler.cs and src/officecli/Handlers/ExcelHandler.cs. These handlers verify element compatibility, ensure target indices fall within document limits, and sanitize style-related side effects to prevent document corruption.

Summary

• OfficeCLI move and swap commands enable command-line reorganization of Word, Excel, and PowerPoint documents.
• Both commands use a selector-positional model (p[n], table[n], sheet[name], etc.) to target elements.
• The move command relocates single elements, while swap exchanges two elements' positions.
• Operations generate patches in watch-overlay.js (~line 296) and process through SelectorPositionalIndex.cs for XML rewriting.
• Real-time synchronization occurs via SSE events handled by watch-sse-core.js.
• Validation layers in WordHandler.cs and ExcelHandler.cs ensure operation safety.

Frequently Asked Questions

What selector syntax does OfficeCLI use for move and swap operations?

OfficeCLI uses a bracket-based selector syntax where p[n] targets the nth paragraph, table[n] targets tables, slide[n] targets PowerPoint slides, and sheet[name] targets Excel worksheets by name. You can nest selectors using forward slashes, such as slide[2]/chart[3], to address elements within containers.

How does OfficeCLI handle move and swap operations without corrupting document XML?

The CLI employs the SelectorPositionalIndex class in src/officecli/Core/SelectorPositionalIndex.cs to calculate precise positional indices before rewriting the underlying XML. Additionally, validation handlers like WordHandler.cs and ExcelHandler.cs check element compatibility and boundary constraints before applying changes, ensuring the document structure remains valid.

Can I move elements between different slides or worksheets?

Yes. The selector syntax supports cross-container operations when you specify full paths. For example, moving a chart from slide 3 to slide 1 requires the syntax slide[3]/chart[1] as the source and slide[1] as the target. The server-side logic in SelectorPositionalIndex.cs recalculates the positional indices for the new container context.

What happens if the target index is out of bounds?

The validation layer in the document-specific handlers (WordHandler.cs, ExcelHandler.cs, etc.) checks that target indices exist within the document's current structure. If you attempt to move an element to a position that exceeds the document's limits, the operation fails before any XML modification occurs, returning an error to the CLI without corrupting the file.

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