How to Create PowerPoint Shapes with Geometry Presets, Gradients, and Pattern Fills Using OfficeCLI

OfficeCLI creates and styles PowerPoint shapes by sending JSON batch commands through the Document.batch method, allowing you to set geometry presets, gradient fills, and pattern fills via a unified property-based protocol.

OfficeCLI is an open-source command-line interface and Node SDK for automating Microsoft Office documents. When working with PowerPoint presentations, you can programmatically define shape appearance—including geometric outlines, color gradients, and pattern overlays—by constructing batch items that target specific shape paths within the presentation structure.

Understanding the OfficeCLI Command Protocol

OfficeCLI communicates with a resident Office process using a JSON-based batch protocol. Every shape styling operation is encapsulated as a batch item containing three core fields.

The Batch Item Structure

Each batch item follows this schema:

• command – The operation verb, typically "set" for modifying properties
• path – A URI-like reference to the target object (e.g., /Slide1/Shapes/Shape1)
• props – A map of property names and values to apply

The Node SDK forwards these batches through the Document.batch method, implemented around lines 496-506 in sdk/node/index.js. This method builds a batchJson payload and transmits it to the resident process, which maps the path to the actual PowerPoint object model.

Setting Geometry Presets for PowerPoint Shapes

PowerPoint shapes support geometry presets that define the base outline of the shape. You set these using the geometryPreset property within the batch item's props object.

The preset names correspond to PowerPoint's internal enumeration. Common values include RoundedRectangle, Ellipse, RightArrow, and Star5.

{
  "command": "set",
  "path": "/Slide1/Shapes/MyShape",
  "props": {
    "geometryPreset": "RoundedRectangle"
  }
}

When the resident process receives this command, it applies the specified geometry to the shape located at the given path, transforming the shape's outline to match the preset definition.

Applying Gradient Fills to Shapes

Gradient fills create smooth color transitions across a shape's surface. In OfficeCLI, you define gradients through a nested fill object where type is set to "gradient" and the gradient field contains direction and color stop definitions.

{
  "command": "set",
  "path": "/Slide1/Shapes/MyShape",
  "props": {
    "fill": {
      "type": "gradient",
      "gradient": {
        "direction": "horizontal",
        "stops": [
          { "offset": 0, "color": "#FF5733" },
          { "offset": 0.5, "color": "#33C1FF" },
          { "offset": 1, "color": "#3357FF" }
        ]
      }
    }
  }
}

Supported directions include vertical, horizontal, and diagonal. Each stop requires an offset value between 0 and 1, and a hex color string. The resident process translates these values into Office Open XML gradient definitions.

Configuring Pattern Fills

Pattern fills overlay geometric textures onto shapes using foreground and background colors. Set fill.type to "pattern" and provide a pattern object containing the pattern name and color specifications.

{
  "command": "set",
  "path": "/Slide1/Shapes/MyShape",
  "props": {
    "fill": {
      "type": "pattern",
      "pattern": {
        "name": "DiagonalCross",
        "foregroundColor": "#FFFFFF",
        "backgroundColor": "#000000"
      }
    }
  }
}

Available pattern names include DiagonalCross, Cross, and other PowerPoint standard patterns. The foregroundColor defines the pattern line color, while backgroundColor fills the spaces between pattern elements.

Complete Implementation Examples

You can combine geometry presets, gradients, and patterns in a single batch operation. Below are implementations using both the Node SDK and the pure CLI interface.

Node SDK Approach

The Node SDK provides a typed interface through the open function and Document.batch method. This example creates a star shape with a diagonal gradient:

import { open } from '@iOfficeAI/officecli';

(async () => {
  const doc = await open('presentation.pptx');
  
  await doc.batch([
    {
      command: 'set',
      path: '/Slide2/Shapes/StarShape',
      props: {
        geometryPreset: 'Star5',
        fill: {
          type: 'gradient',
          gradient: {
            direction: 'diagonal',
            stops: [
              { offset: 0, color: '#FFD700' },
              { offset: 1, color: '#8B0000' }
            ]
          }
        }
      }
    }
  ]);
  
  await doc.close();
})();

The batch method queues the operation and transmits it to the Office resident process, applying all specified properties atomically.

Pure CLI Approach

For shell scripts or one-off operations, use the officecli batch command with inline JSON:

officecli batch presentation.pptx \
  --json '[
    {
      "command": "set",
      "path": "/Slide3/Shapes/RectShape",
      "props": {
        "geometryPreset": "RoundedRectangle",
        "fill": {
          "type": "pattern",
          "pattern": {
            "name": "Cross",
            "foregroundColor": "#FF00FF",
            "backgroundColor": "#FFFF00"
          }
        }
      }
    }
  ]'

The CLI parses the JSON array, validates the batch structure, and forwards the commands to the resident process handling the specified .pptx file.

Architecture and Source Code References

Understanding the underlying implementation helps debug complex shape operations.

Batch Processing Core – The Document.batch implementation in sdk/node/index.js (lines 496-506) constructs the JSON payload and manages the communication channel with the Office resident process.

Shape Detection – The file src/officecli/Resources/watch-overlay.js contains the logic for identifying PowerPoint shape objects and routing non-cell commands. This resource handles the translation from JSON paths to actual shape instances within the presentation's object model.

Type Definitions – The TypeScript definitions in sdk/node/index.d.ts document the batch method signature and available property interfaces for SDK consumers.

Summary

• OfficeCLI uses a JSON batch protocol with command, path, and props fields to manipulate PowerPoint shapes.
• Set geometry presets using the geometryPreset property with values like RoundedRectangle or Star5.
• Configure gradient fills by setting fill.type to "gradient" and defining direction and color stops.
• Apply pattern fills by setting fill.type to "pattern" and specifying pattern names with foreground and background colors.
• The Document.batch method in sdk/node/index.js forwards operations to the resident process, while src/officecli/Resources/watch-overlay.js handles shape-specific routing.

Frequently Asked Questions

What JSON structure does OfficeCLI expect for shape styling?

OfficeCLI expects batch items containing three fields: command (typically "set"), path (the URI-like location such as /Slide1/Shapes/Shape1), and props (an object containing geometryPreset, fill, or other style properties). The resident process validates this structure before applying changes to the presentation.

Can I combine geometry presets with multiple fill types in one command?

Yes, you can combine a geometryPreset with either a gradient or pattern fill within the same props object in a single batch item. However, a shape can only have one active fill type at a time; specifying both gradient and pattern in the same fill object would result in the last defined property taking precedence.

Where is the batch processing logic implemented in the OfficeCLI source?

The batch processing logic resides in sdk/node/index.js around lines 496-506, where the Document.batch method serializes the batch array into JSON and transmits it to the Office resident process. The resident side interprets these commands and maps them to the Office Open XML API for shape manipulation.

Does OfficeCLI support all PowerPoint gradient directions?

OfficeCLI supports the standard PowerPoint gradient directions including vertical, horizontal, and diagonal. These values are passed directly to the underlying Office API, ensuring compatibility with PowerPoint's native gradient rendering engine.

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