Simplify CLI: 22 commands → 9 agent-friendly commands

[tmustier]

Problem

The current CLI has 22 commands — too much surface area for an agent to work with effectively:

list, summary, slide, shape, chart, layout, layouts, theme, color, xml,
edit, batch, add-slide, delete-slide, delete-shape, render, crop,
generate, validate, preview, verify, screenshot

An agent has to guess which command to call. Most inspection commands overlap conceptually.

Agent workflow

What an agent actually does with PowerPoint:

1. Understand what's in the file → read structure, shapes, styles
2. Change content → edit text, add/remove slides and shapes
3. Generate structured content → tables from data (YAML pipeline)
4. Verify visually → render to PNG, look at it

Proposed CLI (9 commands)

pptx show     <file> [slide] [shape]          # progressive read
pptx theme    <file>                          # color scheme
pptx xml      <file> <slide> <shape>          # raw XML (escape hatch)

pptx edit     <file> <edits.json>             # always batch, always JSON
pptx add      <file> <layout> [--at N]        # add slide
pptx delete   <file> <slide> [shape]          # delete slide or shape

pptx generate <yaml> [-t template]            # YAML → table
pptx render   <file> [slide] [--crop L,T,R,B] # visual check

Key changes

Before	After	Rationale
list, summary, slide, shape, chart, layout, layouts	show	Progressive drill-down with one command. No args = slide list. Slide num = shapes. Shape = full detail (including chart data if applicable).
color	Fold into show or theme	Rarely used standalone
edit + batch	edit (always batch)	Implementation detail; single edit is batch of 1
add-slide	add	Shorter
delete-slide + delete-shape	delete	Unified; delete 1 = slide, delete 1 3 = shape
render + crop + screenshot	render	One command with optional crop
validate + preview + verify	Remove (inline in generate)	Dev tools, not agent tools; generate validates inline

pptx show behavior

The big win is progressive detail:

pptx show deck.pptx
#   1  Introduction
#   2  Q1 Results
#   3  Roadmap

pptx show deck.pptx 2
#  [0] Title 1            0.61,0.20  12.12x0.80  ph=0  «Q1 Results»
#  [1] Chart 3            2.00,1.50   9.00x5.00       (bar chart, 4 series)
#  [2] TextBox 5          0.61,6.80   5.00x0.50       «Source: Finance»

pptx show deck.pptx 2 1
# { full shape JSON including chart data, formatting, etc. }

Agent learns one pattern, uses it everywhere.

Migration

• Keep old commands as hidden aliases during transition
• Update SKILL.md to document new interface
• Update any tests that call old command names

Checklist

• Implement pptx show with progressive drill-down
• Implement pptx delete (unified slide/shape deletion)
• Consolidate edit + batch → single edit (always JSON)
• Consolidate render + crop + screenshot → single render
• Fold validate/preview/verify into generate (or keep as hidden)
• Rename add-slide → add
• Hide old commands (keep as aliases for backward compat)
• Update SKILL.md
• Update tests