pptx — Template-Bound PowerPoint Generation

pptx is a CLI that turns a real .pptx template into a machine-readable manifest, then generates slides and decks inside the original corporate design contract. It preserves masters, themes, locked branding, and placeholder rules — instead of approximating them.

Quick orientation

The workflow has three phases:

1. Setup — install the CLI and initialize a manifest from a template
2. Discover — explore layouts, placeholders, and theme to understand what's available
3. Build — create slides or full decks from structured specs, then validate

Phase 1: Setup

Install

uv tool install pptx-cli
# or: pip install pptx-cli

Verify with pptx --version.

Initialize a manifest

The manifest package lives at .pptx/ in the project root. Always check for an existing one first:

ls .pptx/manifest.yaml 2>/dev/null

If no manifest exists, you need a .pptx template file from the user. Ask the user to provide one — do not assume a template exists. Then initialize:

pptx init <template.pptx> --out ./.pptx

This extracts layouts, placeholders, assets, themes, and rules into a structured manifest package.

Bootstrap command: pptx guide

Run this once to get the full CLI contract — all commands, schemas, error codes, and examples:

pptx guide --format json

This is your single source of truth for the CLI's capabilities. Cache the result mentally and refer to it throughout the session.

Phase 2: Discover

Before building anything, understand what the template offers. These are all read-only commands and can run in parallel:

# List all available layouts
pptx layouts list --manifest ./.pptx --format json

# Show details for a specific layout
pptx layouts show <layout-id> --manifest ./.pptx --format json

# List placeholders for a layout (tells you what content keys are available)
pptx placeholders list <layout-id> --manifest ./.pptx --format json

# Show theme metadata
pptx theme show --manifest ./.pptx --format json

# List extracted assets
pptx assets list --manifest ./.pptx --format json

# Check for compatibility warnings
pptx doctor --manifest ./.pptx --format json

Layout IDs are slugified names derived from the template (e.g., title-only, 1-title-and-content, 1-breaker-with-pattern). Use layouts list to discover the exact IDs.

Placeholder keys are logical names like title, subtitle, content_1, picture. Use placeholders list <layout-id> to discover the exact keys and their supported content types for each layout.

Phase 3: Build

Single slide

pptx slide create \
  --manifest ./.pptx \
  --layout <layout-id> \
  --set title="Your Title" \
  --set subtitle="Your Subtitle" \
  --out ./out/slide.pptx

Full deck from a spec

Create a YAML or JSON spec file, then build. See references/deck-spec.md for the full spec format.

# deck.yaml
manifest: ./.pptx
metadata:
  title: My Presentation
  author: Author Name
slides:
  - layout: title-only
    content:
      title: Welcome
      subtitle: March 2026
  - layout: 1-title-and-content
    content:
      title: Key Points
      content_1: |
        First point.
        Second point.
        Third point.

pptx deck build \
  --manifest ./.pptx \
  --spec deck.yaml \
  --out ./out/deck.pptx

Preview before writing

Always use --dry-run first on mutating commands to preview what will happen without writing files:

pptx deck build --manifest ./.pptx --spec deck.yaml --out ./out/deck.pptx --dry-run

Validate the output

After generating a deck, validate it against the manifest:

pptx validate --manifest ./.pptx --deck ./out/deck.pptx --strict --format json

Supported content types

• text — plain text
• image — image file reference
• table — structured table data
• chart — chart data
• markdown-to-text — markdown converted to formatted text

Speaker notes are supported separately from placeholder content types. Use a slide-level notes field in deck specs, or pptx slide create --notes / --notes-file for single-slide generation.

Error handling

All commands return a structured JSON envelope with ok, errors, and warnings fields. Key exit codes:

Check ok first, then branch on errors[0].code if it's false.

Typical workflow for building a presentation

1. Check for .pptx/manifest.yaml — if missing, ask user for a template and run pptx init
2. Run pptx layouts list to see available layouts
3. For each layout you plan to use, run pptx placeholders list <layout-id> to discover content keys
4. Draft a deck.yaml spec using only discovered layout IDs and placeholder keys
5. Preview with pptx deck build ... --dry-run
6. Build with pptx deck build ... --out ./out/deck.pptx
7. Validate with pptx validate ...

Key rules

• Only use layout IDs that appear in layouts list — unknown layouts cause validation errors
• Only use placeholder keys that appear in placeholders list — unknown keys are silently ignored or cause errors
• Always use --manifest ./.pptx to point to the manifest package
• Use --dry-run before writing to catch issues early
• Use --format json on read commands to get structured output you can parse

For detailed deck spec format and advanced options, read references/deck-spec.md.