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

> Master OfficeCLI move and swap commands to reorder content in Word, Excel, and PowerPoint. Effortlessly reorganize paragraphs, tables, charts, and slides without opening Office apps. Learn efficient document manipulation.

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

---

**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.

```bash

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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-overlay.js), but with `patch.op === 'swap'`. The server processes this through [`SelectorPositionalIndex.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](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). 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-overlay.js) (~line 296) and process through [`SelectorPositionalIndex.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SelectorPositionalIndex.cs) for XML rewriting.
- Real-time synchronization occurs via SSE events handled by [`watch-sse-core.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js).
- Validation layers in [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) and [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/SelectorPositionalIndex.cs) to calculate precise positional indices before rewriting the underlying XML. Additionally, validation handlers like [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) and [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.