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

> Learn to use OfficeCLI move and swap commands to reorganize document elements like paragraphs tables charts and slides effortlessly. Streamline your workflow today.

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

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-overlay.js) (line ≈ 296). The server-side logic again utilizes [`SelectorPositionalIndex.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs) and [`src/officecli/Handlers/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/SelectorPositionalIndex.cs) to rewrite XML and calculate new indices.
- Validation occurs in [`src/officecli/Handlers/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs) and [`src/officecli/Handlers/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SelectorPositionalIndex.cs) helper handles the distinct index calculations required for each operation type, ensuring proper XML restructuring in both scenarios.