Automating Keynote (JXA-first, AppleScript discovery)

Contents

• •Relationship to the macOS automation skill
• •Core framing
• •Workflow (default)
• •Quick Examples
• •What to load

Relationship to the macOS automation skill

• •This skill focuses on Keynote-specific automation (documents, slides, charts).
• •Use automating-mac-apps for cross-app workflows or general macOS scripting foundations.
• •Assumes Apple Events knowledge from the related skill.
• •PyXA Installation: To use PyXA examples in this skill, see the installation instructions in automating-mac-apps skill (PyXA Installation section).

Core Framing

• •JXA (JavaScript for Automation) enables macOS app scripting with JavaScript syntax.
• •AppleScript dictionaries define Keynote's object model—discover via Script Editor.
• •JXA objects are specifiers: read with methods like .name(), write with assignments.
• •Production scripts use JXA for reliability; AppleScript for prototyping.
• •Important: The JXA Path() function is required when specifying file paths to Keynote (e.g., for images, exports, or opening documents). Use Path("/path/to/file") instead of plain strings.

Workflow (default)

1. •Discover terms in Script Editor > File > Open Dictionary > Keynote.
2. •Prototype minimal AppleScript: tell application "Keynote" to get name of document 1.
3. •Port to JXA: Application("Keynote").documents[0].name() with try-catch blocks.
4. •Validate with read-only probes: Application("Keynote").documents.length > 0.
5. •Use UI scripting only when dictionary lacks features (e.g. Application("System Events")).

Quick Examples

Prototype (AppleScript):

tell application "Keynote"
    get name of document 1
end tell

Production (JXA):

const keynote = Application("Keynote");
if (keynote.documents.length > 0) {
    console.log(keynote.documents[0].name());
}

Create Slide:

const doc = keynote.documents[0];
const slide = doc.slides.push(keynote.Slide({baseSlide: doc.masterSlides['Title - Center']}));
slide.defaultTitleItem.objectText = "New Slide";

Add Image to Slide (note Path() usage):

const slide = doc.slides[0];
const img = keynote.Image({
  file: Path("/Users/you/Desktop/diagram.png"),  // Path() required!
  position: { x: 100, y: 100 },
  width: 800
});
slide.images.push(img);

Validation Checklist

After implementing Keynote automation:

• • Verify Keynote is running and accessible
• • Test slide creation with master slide assignment
• • Confirm image paths use Path() function
• • Check text rendering in default text items
• • Validate export operations complete without errors

When Not to Use

• •For cross-platform presentation automation (use PowerPoint with Python libraries)
• •When AppleScript alone suffices (skip JXA complexity)
• •For web-based presentations (Google Slides, reveal.js)
• •For non-macOS platforms

What to load

• •Keynote JXA basics + runtime caveats: automating-keynote/references/keynote-basics.md
• •Keynote recipes (slides, text, images, export): automating-keynote/references/keynote-recipes.md
• •Deck generator example: automating-keynote/references/keynote-deck-generator.md
• •Chart-aware deck pattern: automating-keynote/references/keynote-chart-aware-deck.md
• •Advanced workflows (charts bridge, magic move, UI scripting): automating-keynote/references/keynote-advanced.md
• •PyXA (Python) practical examples: automating-keynote/references/keynote-pyxa.md
• •PyXA API Reference (complete class/method docs): automating-keynote/references/keynote-pyxa-api-reference.md