How to Use OfficeCLI to Insert Images into PowerPoint Slides: CLI and Python SDK Guide

OfficeCLI inserts images into PowerPoint slides by sending add commands with --type picture and --prop src=... arguments, which create <picture> elements in the target .pptx file.

OfficeCLI from the iOfficeAI/OfficeCLI repository provides a scriptable interface for manipulating PowerPoint files without manual interaction. You can use OfficeCLI to insert images into PowerPoint slides via the command-line tool or the Python SDK, both of which rely on the same underlying pipe protocol and picture schema. This guide explains the exact commands, properties, and source files required to embed, position, and enhance images programmatically.

How OfficeCLI Inserts Images into PowerPoint Slides

Under the hood, OfficeCLI inserts images by sending an add command that describes a picture element. The CLI creates a <picture> element on the target slide and stores the image data in the slide's media folder. All picture attributes are defined and validated against the picture schema located at schemas/help/pptx/picture.json in the repository.

Picture Schema and Supported Properties

The schema at schemas/help/pptx/picture.json documents every accepted field, its type, and usage examples. Properties are categorized by whether they apply during the initial add operation or via a subsequent set command.

Core Layout and Source Properties

• src (alias path): The image source. Accepts a file path, URL, data URI, or raw bytes. This is required for the add command.
• x, y: Absolute position on the slide, specified in EMU or standard length units such as 1in.
• width, height: The display size of the picture, also specified as a length.
• rotation (alias rotate): Clockwise rotation in degrees.
• crop, cropLeft, cropTop, cropRight, cropBottom: Cropping percentages applied to the image edges.
• link: A click-through hyperlink, which can be a URL, slide reference, or named action.
• tooltip: Hover tooltip text displayed when the picture has a hyperlink.

Visual Effects and Set-Only Properties

Certain enhancements cannot be applied during insertion. According to schemas/help/pptx/picture.json, the following properties are restricted to the set command after the picture exists:

• brightness
• contrast
• glow
• shadow

Inserting Images with the OfficeCLI Command-Line Interface

The CLI manipulates .pptx files through sequential commands. The workflow requires creating or opening a presentation, adding a slide, then issuing an add command with --type picture. The complete demonstration lives in examples/ppt/pictures/pictures-basic.sh.

CLI=${1:-officecli}
FILE=demo.pptx

$CLI create "$FILE"
$CLI open "$FILE"

# Add a slide

$CLI add "$FILE" / --type slide

# Insert a picture

$CLI add "$FILE" "/slide[1]" --type picture \
    --prop src="myphoto.png" \
    --prop x=1in --prop y=1.5in \
    --prop width=4in --prop height=3in \
    --prop rotation=45 \
    --prop alt="My photo"

This example targets /slide[1] as the parent. The CLI creates the <picture> element, resolves src="myphoto.png", and places the image at the specified coordinates.

Using the Python SDK to Insert Images

The Python SDK in sdk/python/officecli.py wraps the same pipe protocol. It exposes a context manager via officecli.create() that automatically handles file creation and opening. You then use doc.send() to dispatch command dictionaries, as implemented in examples/ppt/pictures/pictures-basic.py.

import officecli

FILE = "demo-sdk.pptx"
with officecli.create(FILE, "--force") as doc:
    # Add a slide

    doc.send({"command": "add", "parent": "/", "type": "slide"})

    # Insert a picture with a hyperlink

    pic_path = doc.send({
        "command": "add",
        "parent": "/slide[1]",
        "type": "picture",
        "props": {
            "src": "myphoto.png",
            "x": "1in",
            "y": "1.5in",
            "width": "4in",
            "height": "3in",
            "link": "https://example.com",
            "tooltip": "Open example.com"
        }
    })["data"]  # response contains the picture path

    # Apply a set-only effect: brighten the picture

    doc.send({
        "command": "set",
        "path": pic_path,
        "props": {"brightness": "30"}
    })

    doc.send({"command": "save"})

The add command returns the picture path in the data field. You pass this path to a subsequent set command to adjust brightness and other schema-restricted properties.

Advanced Image Source and Layout Options

Beyond local file paths, OfficeCLI supports dynamic image sources and precise layout modifications.

Embedding a Base64 Data URI

For images generated on the fly, pass a base64 data URI to the src property.

DATA_URI=$(base64 < generated.png | tr -d '\n')
$CLI add "$FILE" "/slide[1]" --type picture \
    --prop src="data:image/png;base64,$DATA_URI" \
    --prop x=2in --prop y=2in \
    --prop width=2in --prop height=2in

This technique avoids writing temporary files by encoding the image bytes directly into the command.

Cropping Pictures

Use the crop property to remove a uniform percentage from all edges, or specify directional crops with cropLeft, cropTop, cropRight, and cropBottom.

$CLI add "$FILE" "/slide[1]" --type picture \
    --prop src="logo.png" \
    --prop x=0.5in --prop y=0.5in \
    --prop width=2in --prop height=2in \
    --prop crop=20

This command inserts logo.png and trims 20 percent from every edge.

Summary

• OfficeCLI inserts images into PowerPoint slides using the add command with --type picture, validated against schemas/help/pptx/picture.json.
• The src property accepts file paths, URLs, data URIs, and raw bytes.
• Position and size are controlled with x, y, width, and height using standard length units.
• Effects such as brightness, contrast, glow, and shadow are set-only and must be applied after insertion.
• The Python SDK in sdk/python/officecli.py mirrors the CLI protocol through doc.send() calls.

Frequently Asked Questions

What image sources can I use with OfficeCLI to insert images into PowerPoint slides?

OfficeCLI accepts any valid image source through the src property, including local file paths, remote URLs, base64 data URIs, and raw bytes. The underlying engine resolves the source during the add command and embeds the resulting image into the slide's media folder.

How do I apply visual effects like brightness or shadow to an inserted picture?

Properties such as brightness, contrast, glow, and shadow are defined in schemas/help/pptx/picture.json as set-only fields. After inserting the image with add, target the picture path with a set command and pass the desired effect inside the props object.

Can I rotate or crop an image during insertion?

Yes. The rotation property (alias rotate) accepts degrees for clockwise rotation, and the crop family of properties accepts percentage values. Both can be supplied directly in the add command alongside src, x, and y, as shown in the CLI examples.

Where is the complete picture schema defined in the OfficeCLI repository?

The formal definition lives at schemas/help/pptx/picture.json. This file enumerates all allowed fields, their data types, and whether they apply to add or set operations for picture elements in PowerPoint slides.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}