# How to Use `move` and `swap` Commands for Element Repositioning in OfficeCLI

> Master element repositioning in OfficeCLI with move and swap commands. Learn to use officecli move and officecli swap for efficient file and data organization. Read now.

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

---

**Use `officecli move <file> <source-path> --after/--before/--index <target>` to reposition a single element, and `officecli swap <file> <path-a> <path-b>` to exchange two elements at the same hierarchical level.**

OfficeCLI treats document manipulation as a set of **verbs** that operate across PowerPoint, Excel, and Word formats. The **`move`** and **`swap`** commands provide precise control over element ordering within containers—slides in a deck, rows in a worksheet, cells in a table, or sheets in a workbook. According to the [PPTX SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-pptx/SKILL.md#L286), these verbs are interpreted by the **ResidentServer** dispatcher and delegated to format-specific handlers using XPath-like selectors.

## How `move` and `swap` Work

The CLI parses the first positional argument as the verb. In [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), the `case "move":` and `case "swap":` branches invoke the corresponding mutation logic through the appropriate handler. Both commands use **selector paths** to address elements:

- `/slide[3]` — third slide in a PowerPoint deck
- `/sheet[1]/row[5]` — fifth row in the first worksheet
- `/sheet[2]/cell[4,7]` — cell at column 4, row 7 in the second sheet

### `move` Command Semantics

The **`move`** verb repositions a single element within its container. It supports four location modifiers:

- **`--after <path>`** — place element after the target
- **`--before <path>`** — place element before the target
- **`--index <n>`** — place element at zero-based position *n*
- **`--position <n>`** — alias for `--index` (format-dependent)

`move` works for any container allowing ordering: slides, rows, columns, sheets, or document sections.

### `swap` Command Semantics

The **`swap`** verb exchanges two elements **without** affecting other container members. Critical requirements:

- Both paths must resolve to elements of the **same type**
- Both elements must exist at the **same hierarchical level**
- They may reside in different parent containers (e.g., swapping cells across rows)

Important limitation: `swap` **does not** support sheet reordering in Excel. For that, you must use `move` with `--after` or `--before`—as documented in [XLSX SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md#L362).

## Practical Command Examples

### Move a Slide Within a PowerPoint Deck

```bash
officecli move presentation.pptx /slide[2] --after /slide[5]

```

Slide 2 is repositioned to immediately follow slide 5.

### Swap Two Slides

```bash
officecli swap presentation.pptx /slide[3] /slide[7]

```

Slides 3 and 7 exchange positions. All other slides retain their relative order.

### Move a Row in an Excel Worksheet

```bash
officecli move data.xlsx /sheet[1]/row[10] --index 3

```

Row 10 becomes the third row (zero-based index 3).

### Swap Two Cells in the Same Column

```bash
officecli swap data.xlsx /sheet[1]/cell[2,3] /sheet[1]/cell[8,3]

```

Cell B3 (column 2, row 3) and cell H3 (column 8, row 3) exchange contents.

### Reorder Excel Sheets (Use `move`, Not `swap`)

```bash
officecli move data.xlsx /sheet[4] --before /sheet[2]

```

Sheet 4 is moved to appear before sheet 2. Per the [XLSX documentation](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md#L362), `swap` is intentionally disabled for sheet-level operations.

### Batch Multiple Repositioning Operations

```bash
officecli batch presentation.pptx <<'EOF'
move /slide[9] --after /slide[1]
swap /slide[4] /slide[6]
move /slide[2] --index 5
EOF

```

Three repositionings execute atomically. If any operation fails, the entire batch rolls back.

## Key Implementation Files

| File | Role | Link |
|------|------|------|
| [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) | Core dispatcher implementing `move` and `swap` case branches | [Source](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) |
| [`skills/officecli-pptx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-pptx/SKILL.md) | Slide-specific verb documentation and path syntax | [Lines 286+](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-pptx/SKILL.md#L286) |
| [`skills/officecli-xlsx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md) | Excel-specific behavior including sheet reordering rules | [Lines 251+, 362](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md#L251) |
| [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md) | High-level verb overview and DOM manipulation concepts | [Line 348](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md#L348) |

## Error Handling and Validation

OfficeCLI validates path compatibility before executing `move` or `swap` operations. Common failure modes include:

- **Incompatible element types** — attempting to swap a slide with a shape
- **Cross-container mismatches** — moving an element to a different document type
- **Invalid index positions** — specifying `--index` beyond container bounds

When validation fails, the CLI prints a descriptive error and aborts without modifying the document. Batch operations maintain atomicity—partial changes are never committed.

## Summary

- **`officecli move`** reorders single elements using `--after`, `--before`, `--index`, or `--position` modifiers
- **`officecli swap`** exchanges two elements at the same hierarchical level without affecting siblings
- **Selector paths** use XPath-like syntax: `/slide[n]`, `/sheet[n]/row[m]`, `/sheet[n]/cell[col,row]`
- **Sheet reordering in Excel** requires `move`; `swap` is explicitly unsupported for this operation
- **Batch mode** enables atomic multi-step repositioning via heredoc or file input
- **Validation errors** prevent document corruption by aborting incompatible operations

## Frequently Asked Questions

### Can I move elements between different documents?

No. The `move` and `swap` commands operate within a single file. Cross-document repositioning requires extracting content with `get` and re-inserting with `add` in a second invocation.

### Why does `swap` fail when I try to exchange Excel sheets?

Per the [XLSX SKILL.md source](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md#L362), sheet reordering is intentionally restricted to the `move` verb. Use `officecli move <file> /sheet[n] --before/--after /sheet[m]` instead.

### What happens if my batch command has one invalid path?

Batch operations are atomic. If any path fails resolution or validation, OfficeCLI aborts the entire sequence and leaves the document unmodified.

### Do `move` and `swap` support Word documents?

Yes, when implemented by the Word handler. The verb architecture in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) delegates to format-specific handlers, so support depends on the installed skill module. Check [`skills/officecli-docx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-docx/SKILL.md) for document-specific path syntax.