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

> Learn how to insert images into PowerPoint slides using OfficeCLI. This guide details CLI commands and Python SDK for programmatically adding pictures to your presentations.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-30

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/pptx/picture.json) in the repository.

## Picture Schema and Supported Properties

The schema at [`schemas/help/pptx/picture.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/examples/ppt/pictures/pictures-basic.sh).

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/examples/ppt/pictures/pictures-basic.py).

```python
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.

```bash
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`.

```bash
$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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.