name: ppt-cli description: > Automate Microsoft PowerPoint on Windows via CLI. Use when creating, reading, or modifying PowerPoint presentations from scripts, CI/CD, or coding agents. Supports Slides, Shapes, Text, Charts, Animations, Transitions. Triggers: PowerPoint, presentation, pptx, pptcli, CLI automation.

PowerPoint Automation with pptcli

Preconditions

• Windows host with Microsoft PowerPoint installed (2016+)
• Uses COM interop — does NOT work on macOS or Linux
• Install: dotnet tool install --global PptMcp.CLI

Workflow Checklist

10+ commands? Use pptcli -q batch --input commands.json — sends all commands in one process with automatic session management. See Rule 8.

CRITICAL RULES (MUST FOLLOW)

⚡ Building dashboards or bulk operations? Skip to Rule 8: Batch Mode — it eliminates per-command process overhead and auto-manages session IDs.

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 -q session create C:\path\newfile.pptx  # Creates file + returns session ID

# EXISTING file - use session open
pptcli -q session open C:\path\existing.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. 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 -q session create C:\path\file.pptx     # Returns JSON with sessionId
pptcli -q slide list --session <returned-session-id>
pptcli -q session close --session <returned-session-id> --save

Unclosed sessions leave PowerPoint processes running, locking files.

Rule 4: Slide Layout and Masters

Slides inherit layouts from slide masters:

pptcli -q slide create --session <id> --layout "Title and Content"  # Use a layout
pptcli -q slide list --session <id>                                  # See all slides

Rule 5: Shape and Text Workflow

BEST PRACTICE: Add shapes then set their text/properties

# Step 1: Add a shape to a slide
pptcli -q shape create --session <id> --slide-index 1 --shape-type rectangle

# Step 2: Set text content
pptcli -q text set --session <id> --slide-index 1 --shape-name "Rectangle 1" --text "Hello World"

# Step 3: Apply formatting
pptcli -q shape format --session <id> --slide-index 1 --shape-name "Rectangle 1" --fill-color "#0078D4"

Rule 6: Report File Errors Immediately

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

Rule 7: Use Animations and Transitions Thoughtfully

When adding animations to multiple shapes, apply them in logical order:

# 1. Add entrance animation to title
pptcli -q animation add --session 1 --slide-index 1 --shape-name "Title" --effect "fade-in"

# 2. Add entrance animation to content
pptcli -q animation add --session 1 --slide-index 1 --shape-name "Content" --effect "fly-in" --delay 0.5

# 3. Set slide transition
pptcli -q transition set --session 1 --slide-index 1 --effect "push" --duration 1.0

Rule 8: Use Batch Mode for Bulk Operations (10+ commands)

When executing 10+ commands on the same file, use pptcli batch to send all commands in a single process launch. This avoids per-process startup overhead and terminal buffer saturation.

# Create a JSON file with all commands
@'
[
  {"command": "session.open", "args": {"filePath": "C:\\path\\file.pptx"}},
  {"command": "slide.create", "args": {"layout": "Blank"}},
  {"command": "shape.create", "args": {"slideIndex": 2, "shapeType": "rectangle"}},
  {"command": "session.close", "args": {"save": true}}
]
'@ | Set-Content commands.json

# Execute all commands at once
pptcli -q batch --input commands.json

Key features:

• Session auto-capture: session.open/create result sessionId auto-injected into subsequent commands — no need to parse and pass session IDs
• NDJSON output: One JSON result per line: {"index": 0, "command": "...", "success": true, "result": {...}}
• --stop-on-error: Exit on first failure (default: continue all)
• --session <id>: Pre-set session ID for all commands (skip session.open)

Input formats:

• JSON array from file: pptcli -q batch --input commands.json
• NDJSON from stdin: Get-Content commands.ndjson | pptcli -q batch

CLI Command Reference

Auto-generated from pptcli --help. Use these exact parameter names.

accessibility

Accessibility audit: check alt text, title placeholders, reading order.

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

animation

Animation effect operations: list, add, remove, reorder effects on slides.

Actions: list, add, remove, clear, set-timing, reorder

background

Slide background: get, set solid color, set image, reset to master.

Actions: get, set-color, reset, set-image, set-gradient

chart

Embedded chart operations: create, get info, set title, set type, delete.

Actions: create, get-info, set-title, set-type, delete, set-data, set-legend, read-data, set-axis-title, toggle-data-table

comment

Slide comments: list, add, delete.

Actions: list, add, delete, clear

customshow

Custom slide show management: list, create, delete, run.

Actions: list, create, delete

design

Design operations: themes, colors, fonts, and design knowledge catalog. THEME OPERATIONS (require open presentation): - list, apply-theme, get-colors, list-color-schemes, get-fonts DESIGN KNOWLEDGE CATALOG (query on demand): - list-archetypes / get-archetype: primary unified archetype surface with curated rules plus learned subtype/example coverage when local reference data is available - list-palettes / get-palette: 8 color palettes with hex values - list-style-profiles / get-style-profile: consulting/sales/startup configurations - list-layout-grids / get-layout-grid: exact x/y/w/h positioning coordinates - list-density-profiles / get-density-profile: D1-D5 content density rules - get-context-model: meeting type → audience → density mapping - get-deck-sequence: canonical slide sequences (decision, pitch, review) - get-slide-patterns: advanced consulting layout patterns - get-icon-shapes: native shape icon catalog

Actions: list, apply-theme, get-colors, list-color-schemes, get-fonts, list-archetypes, get-archetype, list-palettes, get-palette, list-style-profiles, get-style-profile, list-layout-grids, get-layout-grid, list-density-profiles, get-density-profile, get-context-model, get-deck-sequence, get-slide-patterns, get-icon-shapes

docproperty

Document property management: read and write presentation metadata like title, author, subject, keywords.

Actions: get, set, get-custom, set-custom

export

Export presentations to PDF, images, or other formats.

Actions: to-pdf, slide-to-image, to-video, print, save-as, all-slides-to-images, extract-text, extract-images, save-copy

file

File management commands for PowerPoint presentations. Handles file validation and metadata retrieval.

Actions: test

headerfooter

Presentation headers and footers: get settings, set date/page number/footer text.

Actions: get, set

hyperlink

Hyperlink management: add, remove, and get hyperlinks on shapes and text.

Actions: add, get, remove, list, validate

image

Image operations: insert pictures into slides.

Actions: insert, crop, set-brightness-contrast, set-transparent-color

master

Slide master and layout operations: list masters, list layouts, get placeholders.

Actions: list, list-shapes, edit-shape-text, list-layouts, delete-unused

media

Media management: insert audio and video files into slides. Supports linking or embedding media files.

Actions: insert-audio, insert-video, get-info, set-playback

notes

Speaker notes: get, set, clear.

Actions: get, set, clear, append, read-all

pagesetup

Slide size and page setup operations.

Actions: get, set-size, set-first-number

placeholder

Slide placeholder operations: list available placeholders, fill text.

Actions: list, set-text, set-image

printoptions

Manage print options: output type, color mode, framing, fit-to-page, hidden slides.

Actions: get, set

proofing

Proofing and language operations: check spelling, get/set language for text.

Actions: check-spelling, set-language, get-language

section

Presentation section management: list, add, rename, delete, and move sections. Sections group slides for easier navigation and organization.

Actions: list, add, rename, delete

shape

Shape management: list, read, create, move, resize, delete, z-order.

Actions: list, read, add-textbox, add-shape, move-resize, delete, z-order, set-fill, set-line, set-rotation, group, ungroup, set-alt-text, copy-to-slide, set-shadow, add-connector, merge, duplicate, flip, set-text-frame, set-gradient-fill, set-glow, set-reflection, set-opacity, read-fill, read-line, find-by-type, copy-formatting, set-action-settings, scale, lock-aspect-ratio, set-soft-edge, read-shadow, add-text-effect, set-3d

shapealign

Shape alignment and distribution operations.

Actions: align, distribute

slide

Slide lifecycle commands: list, read, create, duplicate, move, delete.

Actions: list, read, create, duplicate, move, delete, apply-layout, set-name, clone-with-replace, hide, unhide, get-thumbnail, summary, set-display-master, copy

slideimport

Import slides from another presentation file.

Actions: import

slideshow

Slideshow presentation mode: start, stop, navigate, get status.

Actions: start, stop, goto-slide, get-status, configure

slidetable

Table shape operations: create, read, write cells, add/delete rows and columns, merge cells.

Actions: create, read, write-cell, add-row, add-column, delete-row, delete-column, merge-cells, read-cell, format-cell, write-row, read-row, set-cell-border

smartart

SmartArt diagram operations: create, add/remove nodes, change layout.

Actions: get-info, add-node, set-layout, set-style, delete-node, change-level

tag

Custom tags/metadata on slides and shapes.

Actions: list, set, delete

text

Text operations within shapes: get, set, format, find, replace.

Actions: get, set, find, replace, format, format-advanced, word-count, alt-text-audit, empty-placeholder-audit, set-spacing, set-bullets, insert-link, change-case, read-spacing, read-bullets, insert-symbol, insert-datetime, insert-slide-number

transition

Slide transition effects: get, set, remove.

Actions: get, set, remove, copy-to-all

vba

VBA macro operations: list modules, view/import/delete code, run macros. Requires VBA trust settings enabled in PowerPoint.

Actions: list, view, import, delete, run

window

PowerPoint window management: get info, minimize, restore, maximize.

Actions: get-info, minimize, restore, maximize, set-zoom, set-view, get-view

Common Pitfalls

Slide Indices Are 1-Based

Slide indices start at 1, not 0. --slide-index 0 is invalid and will error.

--timeout Must Be Greater Than Zero

When using --timeout, the value must be a positive integer (seconds). --timeout 0 is invalid and will error. Omit --timeout entirely to use the default (300 seconds for most operations).

Shape Names Must Be Exact

Shape names are case-sensitive and must match exactly. Use shape list to discover correct names before targeting shapes.

JSON Values Format

--values takes a JSON string wrapped in single quotes:

# CORRECT: JSON with single-quote wrapper
--values '{"text": "Hello World", "fontSize": 24}'

# WRONG: Missing quotes
--values {text: Hello World}

List Parameters Use JSON Arrays

Parameters that accept lists require JSON array format:

# CORRECT: JSON array with single-quote wrapper
--selected-items '["Slide 1","Slide 3"]'

# WRONG: Comma-separated string (not valid)
--selected-items "Slide 1,Slide 3"

Reference Documentation

• Core execution rules and LLM guidelines
• Slide design principles
• Slide design review checklist
• Generation pipeline
• Agent mode patterns

For design catalog data (archetypes, palettes, grids, styles, density), use the design CLI command:

• pptcli design list-archetypes / pptcli design get-archetype --archetype-id ... — primary unified archetype surface; includes learned subtypes and concrete sanitized example details when local reference data is available
• pptcli design list-palettes / pptcli design get-palette --palette-id ...
• pptcli design list-layout-grids / pptcli design get-layout-grid --grid-id ...
• pptcli design list-style-profiles / pptcli design get-style-profile --profile-id ...
• pptcli design get-context-model — Meeting type → density mapping
• pptcli design get-deck-sequence --sequence-id ... — Canonical slide sequences

Reference examples are exposed only as sanitized ids/details embedded in get-archetype. Raw filenames and provenance metadata remain in local gitignored reference catalog data and are not part of the public CLI surface.