How to Use OfficeCLI Move and Swap Commands to Reorganize Document Elements

OfficeCLI enables command-line reordering of document elements—including paragraphs, tables, charts, and slides—using the move and swap commands that translate selector-based instructions into XML patches applied through the Office back-end.

The iOfficeAI/OfficeCLI repository provides a command-line interface for manipulating Office documents without launching the native UI. Its move and swap commands implement a selector-positional model that converts high-level element references into concrete DOM operations, allowing you to reorganize Word, Excel, and PowerPoint files programmatically.

How the Selector-Positional Model Works

Both commands operate on selectors that follow the grammar used by the get and set verbs. Selectors address specific document components using syntax such as p[n] for the nth paragraph, table[n] for tables, slide[n] for PowerPoint slides, chart[n] for charts, and sheet[name] for Excel worksheets. You can combine selectors with path separators (/) to target nested elements, such as slide[2]/chart[3].

The CLI resolves these selectors to concrete DOM nodes and translates operations into patches that the Office back-end applies. After server-side processing, changes stream back to the client via Server-Sent Events (SSE) to synchronize the interface.

Moving Single Elements with the move Command

The move command relocates a single element to a new index within the document structure. When you execute a move operation, the CLI invokes the handler in src/officecli/Resources/watch-overlay.js at approximately line 296, which constructs a patch of type move. This patch streams to the Office back-end, where the SelectorPositionalIndex helper in src/officecli/Core/SelectorPositionalIndex.cs calculates the new positional indices and rewrites the underlying XML.

After the server updates the document, the SSE listener in src/officecli/Resources/watch-sse-core.js receives the patch with patch.op === 'move' and re-applies the selection to keep the UI synchronized without a full refresh.

Swapping Element Positions with the swap Command

The swap command exchanges the positions of two distinct elements. Similar to the move workflow, the client creates a patch of type swap processed through watch-overlay.js (line ≈ 296). The server-side logic again utilizes SelectorPositionalIndex.cs to recalculate indices and modify the document XML. The SSE core subsequently publishes the swap event, which the overlay consumes to update the DOM directly.

Server-Side Validation and XML Processing

Before applying any patch, the validation layer in src/officecli/Handlers/WordHandler.cs and src/officecli/Handlers/ExcelHandler.cs checks element compatibility and ensures target indices remain within document limits. This layer sanitizes style-related side effects and prevents operations that would corrupt the document structure. The src/officecli/CommandBuilder.cs file registers both move and swap verbs, mapping them to their respective handler implementations.

Practical Command Examples

Use the following syntax to execute move and swap operations from your terminal:

# Move the 5th paragraph of a Word document to become the 2nd paragraph

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

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

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

# 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]"

Summary

• OfficeCLI provides move and swap commands for reorganizing document elements via command-line interface.
• Both commands use a selector-positional model targeting paragraphs, tables, charts, slides, and worksheets using syntax like p[n], table[n], and slide[n].
• The client generates patches in src/officecli/Resources/watch-overlay.js (~line 296) that stream to the server via SSE.
• Server-side processing relies on src/officecli/Core/SelectorPositionalIndex.cs to rewrite XML and calculate new indices.
• Validation occurs in src/officecli/Handlers/WordHandler.cs and src/officecli/Handlers/ExcelHandler.cs to ensure compatibility and bounds checking.
• Selectors support nested paths using / separators and name-based references for Excel sheets.

Frequently Asked Questions

Can I swap elements of different types, such as a paragraph and a table?

The validation layer in WordHandler.cs checks element compatibility before executing swaps. While the selector grammar allows targeting any element, the underlying XML structure and validation rules may restrict swapping incompatible types to preserve document integrity and prevent formatting corruption.

Which Office file formats support the move and swap commands?

The commands support Word documents (.docx), Excel workbooks (.xlsx), and PowerPoint presentations (.pptx), as implemented in the respective handler files including WordHandler.cs, ExcelHandler.cs, and their PowerPoint siblings within src/officecli/Handlers/.

How does the CLI update the user interface after a move operation?

After the server applies the patch, the SSE listener in src/officecli/Resources/watch-sse-core.js receives the operation event and updates the DOM directly. This mechanism ensures the UI stays synchronized with the underlying document XML without requiring a full page refresh.

What is the difference between the move and swap patch types?

While both use the same SSE transport and validation layer, a move patch relocates a single element to a new index, whereas a swap patch exchanges the positions of two elements. The SelectorPositionalIndex.cs helper handles the distinct index calculations required for each operation type, ensuring proper XML restructuring in both scenarios.

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