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

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

Practical Command Examples

Move a Slide Within a PowerPoint Deck

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

Slide 2 is repositioned to immediately follow slide 5.

Swap Two Slides

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

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

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)

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

Sheet 4 is moved to appear before sheet 2. Per the XLSX documentation, swap is intentionally disabled for sheet-level operations.

Batch Multiple Repositioning Operations

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	Core dispatcher implementing move and swap case branches	Source
skills/officecli-pptx/SKILL.md	Slide-specific verb documentation and path syntax	Lines 286+
skills/officecli-xlsx/SKILL.md	Excel-specific behavior including sheet reordering rules	Lines 251+, 362
README.md	High-level verb overview and DOM manipulation concepts	Line 348

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, 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 delegates to format-specific handlers, so support depends on the installed skill module. Check skills/officecli-docx/SKILL.md for document-specific path syntax.

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