Powerpoint CLI

PowerPoint Automation with pptcli

Preconditions

• Windows host with Microsoft PowerPoint installed (2016+)
• Uses COM interop — does NOT work on macOS or Linux
• Requires pptcli.exe on PATH (dotnet tool install --global Sbroenne.PowerPointMcp.CLI)

How pptcli Works — a Background Daemon, Not a Cold Start Per Command

Launching PowerPoint and tearing it down again can take 90-150 seconds. To avoid paying that cost on every single CLI invocation, pptcli keeps one PowerPoint instance alive in a small background daemon (pptcli service run), auto-started the first time you open or create a session, and reused by every subsequent command that references the same session id — even though each command is a separate OS process.

Workflow Checklist

CRITICAL RULES (MUST FOLLOW)

Rule 1: NEVER Ask Clarifying Questions

Execute commands to discover the answer instead:

You have commands to answer your own questions. USE THEM.

Rule 2: Always End With a Text Summary

NEVER end your turn with only a command execution. After completing all operations, always provide a brief text message confirming what was done. Silent command-only responses are incomplete.

Rule 3: Session Lifecycle

Creating vs Opening Files:

# NEW file - use session create
pptcli session create C:\decks\demo.pptx   # Creates file + returns session ID

# EXISTING file - use session open
pptcli session open C:\decks\demo.pptx     # Opens file + returns session ID

CRITICAL: Use session create for new files. session open on non-existent files will fail!

CRITICAL: ALWAYS use the session ID returned by session create or session open in subsequent commands via -s/--session. NEVER guess or hardcode session IDs. The session ID is in the JSON output (e.g., {"sessionId":"abc123"}). Parse it and use it.

# Example: capture session ID from output, then use it
pptcli session create C:\decks\demo.pptx        # Returns JSON with sessionId
pptcli slide add-blank -s <returned-session-id>
pptcli session close <returned-session-id> --save

Unclosed sessions leave PowerPoint processes running, locking files — but the daemon shuts down automatically after an idle period with no open sessions, or immediately via pptcli service stop.

Rule 4: 1-Based Indexing Everywhere

--slide-index, --shape-index, --row, --column are all 1-based, matching PowerPoint's native object model — not 0-based.

Rule 5: Restyling an Existing Deck via a .potx Template

$session = pptcli session open C:\decks\demo.pptx | ConvertFrom-Json
pptcli presentation apply-template -s $session.sessionId --template-path C:\templates\corp.potx
pptcli presentation get-theme-name -s $session.sessionId   # verify the theme actually changed
pptcli session close $session.sessionId --save

Slide content is preserved; only masters/theme/layouts change.

Rule 6: Mark as Final Is Advisory, Not Security

pptcli session get-final <session-id>
pptcli session set-final <session-id> true
pptcli session set-final <session-id> false

Mark as Final only communicates that editing is discouraged. It is not authentication, encryption, or access control. Setting it to true first saves all current changes, then PowerPoint persists the flag and makes the presentation read-only; session close --save remains valid without losing edits made before set-final. After clearing the flag, close with --save to persist the cleared state.

Rule 7: Report File Errors Immediately

If you see "File not found" or "Path not found" - STOP and report to user. Don't retry.

Rule 8: Managing the Daemon Directly

pptcli service status         # Report starting/running/unresponsive/stopped state
pptcli service stop           # Graceful shutdown
pptcli service stop --force   # Stop only PID + start-time identities owned by this daemon

CLI Command Reference

Syntax rule: CLI commands use pptcli <command> <action> -s <SESSION_ID> --kebab-case-flags .... Do not use MCP call syntax such as shape(action: "add-rectangle", session_id: ..., slide_index: ...) or snake_case parameters — the CLI uses kebab-case flags and a <command> <action> shape instead of one flat tool per verb.

Available command groups (in addition to session and service):

accessibility, animation, chart, export, image, layout, master, media, notes, pagesetup, shape, slide, smartart, table, textframe

Run pptcli <command> --help for the live, authoritative list of actions and flags for that command — the table below is a summary generated from the same Core interfaces as the MCP tool surface, so it can lag a --help run for in-flight changes.

accessibility — Deterministic presentation accessibility checks and reading-order operations.

Actions: audit, get-reading-order, set-reading-order

animation — Animation commands: add/delete entrance, emphasis, and exit effects on a shape's slide timeline (Slide.TimeLine.MainSequence), and read/set a slide's transition (Slide.SlideShowTransition). Operates within an already-open , targeting a specific slide (and, for shape effects, a specific shape) by 1-based index.

Actions: add-effect, get-effect-count, delete-effect, get-transition, set-transition

chart — Chart lifecycle, data, and quick-formatting operations.

Actions: add-chart, get-chart-data, add-series, set-chart-title, get-chart-title, set-axis-title, get-axis-title, set-legend-visibility, get-legend-visibility, replace-chart-data, get-style, set-style, get-color-style, set-color-style, get-data-table, set-data-table

export — Export commands: render presentations to PDF or slides to raster image files. Operates within an already-open .

Actions: export-to-pdf, export-slide-to-image, export-all-slides-to-images

image — Image commands: add a picture file to a slide. Operates within an already-open IPresentationBatch, targeting a specific slide by its 1-based index.

Actions: add-picture, set-brightness-contrast, get-brightness-contrast, set-recolor, get-recolor, set-crop, get-crop

layout — Slide layout commands: apply/read a slide's built-in layout. Operates within an already-open IPresentationBatch, targeting a specific slide by its 1-based index.

Actions: set-layout, get-layout, list-layouts, delete-layout

master — Slide master commands: read/edit the title and body placeholder fonts on the presentation's slide master, and read/edit the slide master's background fill color. Operates within an already-open . Changes here apply to every slide that inherits from the master (i.e. any slide that does not itself override the property), which is the practical "edit the master, not each slide" workflow PowerPoint's COM object model supports safely.

Actions: get-title-font, set-title-font, get-body-font, set-body-font, get-background-color, set-background-color, set-gradient-background, get-gradient-background, list-masters, delete-master

media — Media commands: insert audio or video files and inspect their PowerPoint media metadata. Operates within an already-open presentation session using 1-based slide and shape indexes.

Actions: add-media, get-media-info

notes — Speaker notes commands: set/get the notes text for a slide. Operates within an already-open IPresentationBatch, targeting a specific slide by its 1-based index.

Actions: set-notes-text, get-notes-text

pagesetup — Presentation-wide slide size, numbering, and footer settings.

Actions: get-settings, set-size, set-first-slide-number, get-footer, set-footer

shape — Shape commands: create, inspect, format, group, link, and edit native placeholders. Operates within an already-open IPresentationBatch, targeting a specific slide by its 1-based index.

Actions: add-rectangle, add-text-box, add-auto-shape, add-line, add-connector, get-count, delete, set-position, set-size, set-fill, get-fill, set-line, get-line, set-rotation, get-rotation, flip, set-z-order, set-shadow, get-shadow, set-glow, get-glow, set-reflection, get-reflection, set-soft-edge, get-soft-edge, set-bevel, get-bevel, group, ungroup, set-name, get-name, set-alt-text, get-alt-text, set-hyperlink, get-hyperlink, remove-hyperlink, get-link-info, update-link, break-link, set-link-auto-update, list-placeholders, set-placeholder-text, set-placeholder-image, set-tag, get-tag, list-tags, delete-tag

slide — Slide lifecycle, background, section, legacy comment, and slide-import commands.

Actions: add-blank, get-count, delete, duplicate, move-to, set-background-color, get-background-color, set-gradient-background, get-gradient-background, add-section, rename-section, delete-section, get-section-count, get-section-name, list-comments, add-comment, delete-comment, clear-comments, import-from-file, set-tag, get-tag, list-tags, delete-tag

smartart — SmartArt commands: add a SmartArt diagram to a slide from PowerPoint's built-in layout gallery, and add/read/update/delete/count the diagram's nodes. Operates within an already-open , targeting a specific slide and shape by 1-based index.

Actions: add-smart-art, add-node, add-child-node, set-node-text, get-node-text, delete-node, get-node-count

table — Table commands: add a table shape, read/write cell text, insert/delete rows and columns, format cell fill and borders, and merge cells. Operates within an already-open IPresentationBatch, targeting a specific slide and table shape by their 1-based indices.

Actions: add-table, set-cell-text, get-cell-text, insert-row, delete-row, insert-column, delete-column, set-cell-fill, get-cell-fill, set-cell-border, get-cell-border, merge-cells

textframe — Text frame commands: set/get text and basic font formatting (size, bold, italic, underline, font name, color, alignment, bullets) for a shape's text range. Operates within an already-open IPresentationBatch, targeting a specific shape by its 1-based slide and shape index.

Actions: set-text, get-text, set-font-size, get-font-size, set-bold, get-bold, set-font-color, get-font-color, set-italic, get-italic, set-underline, get-underline, set-font-name, get-font-name, set-alignment, get-alignment, set-bullet, get-bullet, set-auto-size, get-auto-size

Common Pitfalls

• --red/--green/--blue for textframe set-font-color are each 0-255 integers, not a single hex string.
• A session created with session create is already open — do not call session open on the same path again; that opens a SECOND session against the same file.