with one click
clean-slides
// Inspect, edit, and generate PowerPoint slides. Progressive drill-down inspection, text editing with formatting preservation, table generation from YAML, and PNG rendering for verification.
// Inspect, edit, and generate PowerPoint slides. Progressive drill-down inspection, text editing with formatting preservation, table generation from YAML, and PNG rendering for verification.
| name | clean-slides |
| description | Inspect, edit, and generate PowerPoint slides. Progressive drill-down inspection, text editing with formatting preservation, table generation from YAML, and PNG rendering for verification. |
Use the pptx CLI for all PowerPoint operations.
Before generating slides, ensure the project has a .clean-slides/ directory. The CLI auto-discovers template.pptx and config.yaml from there — no flags needed.
# Quick start — uses the bundled example template
pptx init
# With a custom/corporate template
pptx init -t path/to/corporate-template.pptx
This creates .clean-slides/template.pptx and .clean-slides/config.yaml. All pptx generate commands in that directory tree will use them automatically.
If no .clean-slides/ directory exists, the CLI prints a hint suggesting pptx init.
Explicit flags always win:
# Override template and config for a single run
pptx generate spec.yaml -t other.pptx -c other-config.yaml -o output.pptx
See examples/custom-template/README.md for a full walkthrough of custom template setup.
# 1. Inspect — progressive drill-down
pptx show deck.pptx # slide list
pptx show deck.pptx 3 # shapes on slide 3
pptx show deck.pptx 3 5 # full detail for shape [5]
# 2. Edit — shape identified by index or name
pptx edit deck.pptx 3 5 "New text" --out edited.pptx
# 3. Verify — render to PNG
pptx render edited.pptx 3 --out images/
pptx show <file> # slides with layout, shape count, word count
pptx show <file> <slide> # all shapes sorted top→bottom, left→right
pptx show <file> <slide> <shape> # full JSON: text runs, formatting, chart data
pptx layouts <file> # available slide layouts with placeholders & content areas
pptx theme <file> # color scheme (accent1, accent2, etc.)
pptx xml <file> <slide> <shape> # raw OOXML for debugging
Run pptx layouts on your template before generating — it shows each layout's fillable placeholders (title, subtitle, tracker, logo, etc.) and content areas with dimensions. Layouts with a secondary content area (e.g. 2/3, 3/4) have a sidebar for supporting content like key takeaways, charts, or images.
Shape types in output: ph0 (placeholder), text, chart, image, group, line, shape
pptx edit <file> <slide> <shape> <text> [--out PATH]
pptx batch <file> <edits.json> [--out PATH]
Text formats — inspect output = edit input:
{"paragraphs": [
{"runs": [
{"text": "Bold ", "bold": true},
{"text": "normal"}
], "level": 0}
]}
Run fields: text, font, size, bold, italic, underline, color, superscript, subscript
"bold": true → explicitly bold"bold": false → explicitly not bold (overrides inherited)pptx add-slide <file> <layout> [--at N] [--out PATH]
pptx delete-slide <file> <slide> --confirm [--out PATH]
pptx delete-shape <file> <slide> <shape> [--out PATH]
pptx insert <deck.pptx> <source.pptx> [--at N] [--slides 1,3-5] [--out PATH]
# 1. Generate the table slide (title/subtitle are set in the YAML)
pptx generate spec.yaml -t template.pptx -o /tmp/table.pptx
# 2. Insert at position 8, pushing old slide 8 → 9
pptx insert deck.pptx /tmp/table.pptx --at 8 --out deck.pptx
# 3. Delete the old slide (now at position 9)
pptx delete-slide deck.pptx 9 --confirm --out deck.pptx
# 4. Verify
pptx render deck.pptx 8 --out renders/
pptx render <file> <slides> [--out DIR] [--dpi N]
pptx crop <png> <L> <T> <R> <B> [--out PATH]
<slides> accepts single (3), list (1,8,16), or ranges (1,3-5,8). Multiple slides share one PDF conversion.
Coordinates for crop are in inches (matches shape positions from show).
Context: pptx generate accepts multiple YAML files and produces one deck with one slide per YAML, in input order.
pptx generate spec.yaml -o output.pptx
pptx generate slide1.yaml slide2.yaml slide3.yaml -o output.pptx
pptx generate spec.yaml -t template.pptx -o output.pptx
pptx generate spec.yaml -t template.pptx -c config.yaml -o output.pptx
pptx validate spec.yaml
pptx verify spec.yaml --detail
Top-level YAML keys (all optional, set before table:):
title — required — fills the title placeholdersubtitle — fills the subtitle placeholdertracker — fills the on-page tracker (supports \n for line breaks)slide_layout — template layout name (e.g. "Default", "2/3", "3/4")content_layout — content area policy: default (below header) or full (near top)sidebar — formatted paragraphs for the secondary content area in split layouts (2/3, 3/4, 1/2)See INPUT-SCHEMA.md for the complete schema.
Text strings in cells, headers, and sidebar support markdown-style inline formatting:
**bold text** → bold*italic text* → italic[link text](https://example.com) → clickable hyperlink (blue, underlined)By default, columns are sized automatically based on content (wider for cells that need more wrapping room). Override with column_widths:
table:
column_widths: equal # equal body columns — best when columns are items being compared
column_widths: [1, 2, 1, 1] # manual proportions
The tool ships with a built-in template config, but supports any PowerPoint template. The workflow is: inspect the template, generate a config, review/adjust, then generate slides.
pptx layouts template.pptx # see all layouts, placeholders, content areas
pptx theme template.pptx # see theme color scheme (dk1, lt1, accent1, etc.)
pptx show template.pptx 1 # inspect shapes on a sample slide
pptx xml template.pptx 1 <shape> # raw XML for bullet lstStyle details
What to look for:
pptx init-config template.pptx -o template-config.yaml
This auto-extracts:
The output is a complete, valid config with sensible defaults for everything — but some values will need adjustment.
Key areas to verify and adjust:
colors: The auto-extracted electric_blue and cyan may not map correctly to your template's accent colors. Compare with pptx theme output and adjust.
fonts: The theme's major/minor fonts may differ from what the template actually uses on slides. Inspect a content slide (pptx show template.pptx 2 <shape>) and check the actual font in use.
font_sizes: Defaults are conservative (12pt body). Check your template's actual type scale and adjust title, body, table sizes.
placeholders: Verify title (usually 0) and subtitle (usually 1) are correct. If your template has a tracker/breadcrumb placeholder, set its index. Remove tracker if there isn't one.
default_colors: These control what theme color names are used for body text (tx1), headers (tx1 or accent1), dividers, and links. Adjust to match your template's design language.
bullets: The hardest to auto-detect. If your template has custom bullet styles with specific chars (•, –, ›) and indentation, inspect the slide master lstStyle:
pptx xml template.pptx 1 <content-placeholder>
# Look for <a:lstStyle> with <a:lvl1pPr>, <a:lvl2pPr>, etc.
Update bullet chars, mar_l_emu, indent_emu, and spacing to match.
layout: The auto-detected margins and Y positions are estimates. If slides look misaligned, measure positions from pptx show template.pptx <slide> output and adjust content_start_y_emu, footer_line_y_emu, etc.
# Generate
pptx generate spec.yaml -t template.pptx -c template-config.yaml -o output.pptx
# Validate / verify also accept --config
pptx validate spec.yaml -c template-config.yaml
pptx verify spec.yaml -c template-config.yaml --detail
-t template.pptx, the generator reads content area dimensions from the actual slide layout placeholders, so layout geometry often works even with approximate config valuesBefore editing, save a backup:
cp deck.pptx deck.backup.pptx
pptx edit deck.pptx ... --out deck.edited.pptx
Always use --out to write to a new file unless explicitly asked to overwrite.
show to find the right shape index