How to Use OfficeCLI to Modify PowerPoint Slide Content: A Complete Guide

OfficeCLI modifies PowerPoint files through the PowerPointHandler class by parsing add, set, and save commands into Open XML mutations that update slides, shapes, and charts via selector paths like /slide[1]/shape[2].

OfficeCLI is an open-source command-line tool that lets you modify PowerPoint slide content programmatically without launching the desktop applications. According to the iOfficeAI/OfficeCLI source code, the PowerPointHandler class in src/officecli/Handlers/PowerPointHandler.cs opens .pptx packages with the Open XML SDK, enumerates document parts, and tracks shape IDs so every new element receives a unique identifier. Because all mutations happen in memory, you can chain multiple add and set operations and persist the final result atomically without corrupting the original file.

How OfficeCLI Handles PowerPoint Files

The entry point for .pptx automation is the PowerPointHandler class, which implements the IDocumentHandler interface. It opens the package using the Open XML SDK, enumerates parts, and maintains an internal registry of shape IDs to prevent collisions when new elements are inserted.

Command Dispatching and File Routing

File extension routing happens in src/officecli/Handlers/DocumentHandlerFactory.cs, which dispatches .pptx, .docx, and .xlsx files to their respective handlers. When you run a command, the CLI parses the selector path—such as /slide[1] or /slide[2]/shape[3]—and forwards the instruction to the PowerPointHandler for validation and execution.

Adding Slides, Shapes, and Charts

New content is created through the builder logic in src/officecli/CommandBuilder.Add.cs. This class translates officecli add … instructions into concrete Open XML nodes, including slides, shapes, and charts.

Create a New Slide

To add a slide at the root level, target the / selector and set the --type to slide:

officecli add deck.pptx / --type slide --prop title="Quarterly Review"

Insert a Shape

You can insert a rectangle or other shape on a specific slide by targeting /slide[N]:

officecli add deck.pptx /slide[1] --type shape \
    --prop type=rect \
    --prop x=1in --prop y=1in --prop w=4in --prop h=2in

Embed a Chart

Charts are added as dedicated parts. The following command inserts a pie chart with embedded data on slide 2:

officecli add deck.pptx /slide[2] --type chart \
    --prop chart=pie \
    --prop data="A:40,B:30,C:30"

Modify PowerPoint Slide Content with the set Command

As implemented in iOfficeAI/OfficeCLI, the CommandBuilder.Set class in src/officecli/CommandBuilder.Set.cs processes officecli set commands. It locates existing elements using selector paths and applies property changes such as text, fill, or color.

Selector Path Validation

Selectors follow the Open XML hierarchy. The PowerPointHandler validates every path before mutation and throws a clear error if the slide or shape index does not exist. Valid paths include /slide[1] for a slide and /slide[1]/shape[2] for a nested shape.

Update Text and Colors

The following commands update the text of the first shape on slide 1 and then change the fill color of the first shape on slide 2:

officecli set deck.pptx /slide[1]/shape[1] --prop text="Revenue ↑ 12%"
officecli set deck.pptx /slide[2]/shape[1] --prop fill=FF5733

Persisting Changes Atomically

After any mutation, the PowerPointHandler marks the document with a Modified flag. The save routine in src/officecli/CommandBuilder.Save.cs triggers an atomic write-back through AtomicPackageWriter in OfficeCli.Core. This writes the new .pptx to disk only after the entire package is serialized, preventing file corruption.

Explicit and Implicit Saves

You can persist changes manually:

officecli save deck.pptx

The CLI also implicitly saves on exit if the Modified flag is set, so an explicit save is optional when chaining commands in one invocation.

Complete Workflow Example

Below is an end-to-end script that creates a presentation, adds slides and shapes, modifies content, and persists the results:

# 1. Create a new presentation with a titled slide

officecli add deck.pptx / --type slide --prop title="Quarterly Review"

# 2. Add a second slide with a custom background

officecli add deck.pptx / --type slide \
    --prop title="Key Metrics" \
    --prop background=1A1A2E

# 3. Insert a rectangle on slide 1 and set its text

officecli add deck.pptx /slide[1] --type shape \
    --prop type=rect \
    --prop x=1in --prop y=1in --prop w=4in --prop h=2in
officecli set deck.pptx /slide[1]/shape[1] --prop text="Revenue ↑ 12%"

# 4. Change the fill color of a shape on slide 2

officecli set deck.pptx /slide[2]/shape[1] --prop fill=FF5733

# 5. Add a pie chart on slide 2

officecli add deck.pptx /slide[2] --type chart \
    --prop chart=pie \
    --prop data="A:40,B:30,C:30"

# 6. Persist all modifications

officecli save deck.pptx

Each command maps to a specific builder class:

• add --type slide – Creates a slide node via CommandBuilder.Add.cs.
• add --type shape – Inserts a shape element on the targeted slide.
• set --prop text – Applies text updates through CommandBuilder.Set.cs.
• add --type chart – Generates a Chart part with embedded data.
• save – Commits the in-memory package to disk atomically.

Summary

• PowerPointHandler.cs implements IDocumentHandler to open .pptx files via the Open XML SDK and track shape IDs.
• CommandBuilder.Add.cs translates officecli add commands into new slides, shapes, or chart parts.
• CommandBuilder.Set.cs locates existing elements by selector path and modifies properties to modify PowerPoint slide content such as text and fill color.
• CommandBuilder.Save.cs triggers an atomic write-back via AtomicPackageWriter, ensuring the original file is never corrupted.

Frequently Asked Questions

How does OfficeCLI target a specific shape or slide?

OfficeCLI uses selector paths that mirror the Open XML hierarchy, such as /slide[1] for the first slide or /slide[2]/shape[1] for the first shape on the second slide. The PowerPointHandler validates the path before executing any set command and returns a clear error if the element does not exist.

Can I modify an existing .pptx file without corrupting the original?

Yes. The PowerPointHandler loads the package into memory and marks it with a Modified flag only when changes occur. The AtomicPackageWriter in OfficeCli.Core performs an atomic save through CommandBuilder.Save.cs, writing a new file without altering the original package on disk until the operation completes successfully.

What types of content can I add to a PowerPoint slide using OfficeCLI?

According to the CommandBuilder.Add.cs source in iOfficeAI/OfficeCLI, you can add slides, shapes, charts, and video elements. You specify the content type with the --type flag and pass properties such as title, text, x, y, w, h, chart, or data to configure the new element.

Is it possible to run multiple modifications in one session?

Yes. Because all mutations are performed on an in-memory copy of the package, you can issue multiple add and set commands in a single CLI invocation and then call officecli save once to persist every change simultaneously. The implicit save on exit also flushes changes if you do not call save explicitly.

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