How to Capture a Specific Slide as a PNG Screenshot Using OfficeCLI

OfficeCLI renders any PowerPoint slide to a PNG image using the view command in screenshot mode with the --page option to target a specific slide.

The iOfficeAI/OfficeCLI repository provides a cross-platform command-line interface for automating Microsoft Office document processing. When you need to capture a specific slide as a PNG screenshot using OfficeCLI, the tool leverages native PowerPoint COM automation on Windows—or an HTML-to-PNG fallback pipeline on Linux and macOS—to generate high-fidelity image exports directly from the terminal.

Command Syntax for Single-Slide Capture

The view verb supports multiple output formats, but screenshot mode produces rasterized PNG images. To isolate a specific slide, use the --page parameter with the target slide number.

officecli view presentation.pptx screenshot --page 3 -o slide-3.png

This command executes three distinct operations defined across the codebase:

• Argument Parsing: src/officecli/CommandBuilder.View.cs (lines 21-31) registers the --page, --out (or -o), --screenshot-width, and --screenshot-height options.
• Request Routing: src/officecli/ResidentServer.cs (lines 1520-1590) validates the screenshot mode, extracts the page filter, and delegates to the backend.
• Rendering Engine: src/officecli/Core/PowerPointPngBackend.cs executes COM/IDispatch calls against the PowerPoint application instance to generate the PNG file.

Capturing with Custom Dimensions

By default, OfficeCLI uses a 1600×1200 pixel viewport. The CLI automatically adjusts the height to preserve the slide’s aspect ratio unless you explicitly define both dimensions.

# Auto-adjust height to maintain aspect ratio based on 2400px width

officecli view deck.pptx screenshot --page 5 --screenshot-width 2400 -o slide-5.png

# Force exact dimensions (may distort aspect ratio)

officecli view deck.pptx screenshot --page 2 --screenshot-width 1920 --screenshot-height 1080 -o slide-2.png

Implementation Architecture

Understanding how OfficeCLI processes screenshot requests helps troubleshoot rendering issues and optimize output quality.

CLI Option Definitions

The command-line interface is constructed in src/officecli/CommandBuilder.View.cs. This file centralizes the argument definitions for the view verb, including the screenshot-specific parameters that control pagination and output resolution.

Request Flow and Backend Delegation

When you execute a screenshot command, ResidentServer.cs handles the incoming request flow. The implementation at lines 1520-1590 parses the screenshot mode identifier, resolves the --page filter to identify target slides, and invokes the appropriate rendering backend based on the host operating system.

Native PowerPoint Rendering

On Windows platforms, src/officecli/Core/PowerPointPngBackend.cs performs the actual conversion. This backend initializes the PowerPoint application via COM interop, navigates to the specified slide index, and exports the slide object directly to the PNG format using native Office APIs.

Advanced Screenshot Workflows

Beyond single-slide exports, the screenshot mode supports batch operations and grid layouts.

Multi-Slide Ranges

The --page option accepts ranges for capturing multiple slides in a single command:

officecli view presentation.pptx screenshot --page 1-5 -o slides.png

Contact Sheet Generation

To generate a thumbnail contact sheet of all slides in a grid layout, use the --grid auto flag:

officecli view deck.pptx screenshot --grid auto -o deck-thumbnails.png

Temporary File Output

If you omit the --out parameter, OfficeCLI writes the PNG to a temporary file and prints the absolute path to stdout, enabling shell piping:

officecli view deck.pptx screenshot --page 1

Summary

• Primary Command: Use officecli view [file] screenshot --page [N] to capture a specific slide as a PNG screenshot using OfficeCLI.
• Default Viewport: 1600×1200 pixels with automatic height adjustment to preserve aspect ratio.
• Key Source Files: CommandBuilder.View.cs defines the CLI options, ResidentServer.cs orchestrates the request at lines 1520-1590, and PowerPointPngBackend.cs executes the native rendering.
• Cross-Platform: Windows uses native PowerPoint COM automation; other platforms use an HTML-to-PNG fallback pipeline.
• Flexible Output: Supports single pages, ranges, grid contact sheets, and temporary file generation when --out is omitted.

Frequently Asked Questions

What is the default image size when capturing slides with OfficeCLI?

The default viewport is 1600×1200 pixels. When you specify only --screenshot-width, the CLI automatically calculates the height to maintain the slide’s original aspect ratio. Explicitly setting both --screenshot-width and --screenshot-height overrides this behavior and may introduce distortion.

Does OfficeCLI require Microsoft PowerPoint to be installed to capture PNG screenshots?

On Windows, yes. The PowerPointPngBackend.cs implementation requires PowerPoint to be installed because it uses COM/IDispatch automation to render slides. On Linux and macOS, OfficeCLI falls back to an HTML-to-PNG pipeline that does not require the Office desktop applications, though the rendering fidelity may differ slightly.

How do I capture multiple non-contiguous slides as separate PNG files?

Execute separate commands for each slide index. The --page option supports single integers or contiguous ranges (e.g., 1-5), but does not support comma-separated lists for non-contiguous selection according to the CommandBuilder.View.cs implementation.

Where does OfficeCLI save the PNG file if I omit the --out parameter?

When the -o or --out flag is not provided, the CLI generates a temporary file in the system’s temp directory and outputs the absolute file path to stdout. This allows scripts to capture the path dynamically using command substitution.

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