DeckUse

Headless engine for structural editing of PPTX files.

---

🌤️ Want to skip local setup? Use our cloud processing via https://deckflow.com

🤖 LLM Quickstart

1. Point your coding agent (Cursor, Claude Code, etc.) to DeckUse docs
2. Start issuing commands like:
   • “replace all 2025 with 2026”
   • “extract all titles”
   • “move image on slide 3”

---

👋 Human Quickstart

1. Install DeckUse

npm install -g @deckflow/deckuse

2. Initialize a workspace

deckuse init company.pptx --dir ./company.deck

3. Inspect structure

deckuse list slides ./company.deck
deckuse show slide ./company.deck 3

Note: Path names depend on the slide layout structure. Common paths include title, body, subtitle, footer.

2.1. Shape ID Path Selectors (for nested/grouped shapes)

Some write operations (e.g. via pptx-modifier) address shapes by an ID path: if a shape with id=9 is nested under a parent shape id=6, its ID path is 6,9.

DeckUse supports expressing this in two equivalent forms:

• Recommended (explicit, composable):

deckuse get text <workspace.dir> "slide:1/shape[id=6]/shape[id=9]"

• CLI shorthand (ID path sugar):

deckuse get text <workspace.dir> "slide:1/#6,9"

Both selectors mean: within slide 1, traverse the shape tree by IDs 6 → 9.

3. Filter-based Selectors

Select elements matching specific criteria using [filter] syntax:

Key-Value Filters:

shape[type=textbox]     # All textbox shapes
shape[type=picture]     # All picture shapes
slide[layout=Title]     # All slides using Title layout
layout[path=ppt/slideLayouts/slideLayout1.xml]  # Layout by path

deckuse set text ./company.deck "slide:3/title" "2026 Strategy"

Write commands and -o/--output

• If <workspace> is a workspace directory (e.g. ./company.deck), write commands will modify the workspace only. -o is optional and will export a PPTX if provided.
• If <workspace> is a .pptx file path, write commands require -o and will export the modified PPTX to that path (no init needed).

5. Build PPTX

deckuse commit ./company.deck --output output.pptx

---

Demos

✏️ Text Replacement

Task = “Replace all 2025 with 2026”

deckuse replace ./deck "2025" "2026"
deckuse commit ./deck -o output.pptx

Or directly on a PPTX (no init, requires -o):

deckuse replace ./file.pptx "2025" "2026" -o output.pptx

---

📊 Structure Inspection

Task = “List all slides and titles”

deckuse list slides ./deck

---

🧩 Layout Adjustment

Task = “Move title on slide 3”

deckuse move ./deck "slide:3/title" --left 0.1 --top 0.2

---

💻 CLI

deckuse init file.pptx
deckuse status ./deck
deckuse list slides ./deck
deckuse set text ./deck "slide:1/title" "Hello"
deckuse commit ./deck

---

Concepts

• Workspace — unpacked PPTX directory
• Selector — query language for slides/shapes
• Command model — read / edit
• Commit — rebuild PPTX

---

FAQ

Why use DeckUse instead of editing PPTX directly?

PPTX files are complex OOXML packages. DeckUse provides safe, structured editing without breaking relationships.

Do I need to use init?

Yes for all modifications. Some commands can work directly on PPTX.

Is DeckUse free?

Yes. DeckUse is dual-licensed under AGPL-3.0 (open source) and a commercial license. Open-source use under AGPL-3.0 is free; closed-source / proprietary use requires a commercial license — see License.

Does DeckUse render slides?

No. Use DeckOps Project for rendering and conversion.

---

License

DeckUse is available under a dual license:

1. AGPL-3.0 — free for open-source use that complies with AGPL-3.0 (including network use source disclosure).
2. Commercial License — for closed-source products, proprietary SaaS, or any use that cannot comply with AGPL-3.0. Contact deckflow.com.

See LICENSE for the dual-license notice.

---

Tell your deck what to do, and it updates itself.