OfficeCLI JSON Output Schema for AI Error Recovery: A Complete Technical Guide

OfficeCLI returns a deterministic JSON envelope with success, data, error, and suggestions fields, enabling AI agents to detect failures programmatically and auto-correct without parsing unstructured text.

OfficeCLI was purpose-built for autonomous AI agents manipulating Office documents. Every command that supports --json adheres to a strict schema contract defined in the source code. Understanding this OfficeCLI JSON output schema for AI error recovery lets developers build self-healing automation pipelines that interpret failures, extract actionable guidance, and retry with corrected parameters.

The OfficeCLI JSON Envelope Structure

The foundation of AI-driven error recovery is the envelope's predictable structure. When you append --json to any OfficeCLI command, the output follows this exact contract:

Field	Type	Purpose
success	boolean	true if operation completed; false if any error occurred
data	object	Command-specific payload (element details, lists, paths)
error	object	Present only when success: false; contains code, error, suggestion
warnings	array	Non-fatal notices that don't halt execution

This design lives in ResidentServer.cs, where the OutputFormatter.WrapEnvelope* methods construct the response. The core logic at lines 842-870 handles the envelope assembly and exit code mapping:

• Exit code 0: success: true, operation completed
• Exit code 1: success: false, operation failed with structured error
• Exit code 2: success: true but warnings contains unsupported/deprecated notices

Designing AI-Friendly Error Recovery Loops

The suggestion field is what distinguishes OfficeCLI from conventional CLI tools. When an operation fails, the error object includes a machine-actionable hint enabling automatic correction.

Example: Recovering from a Missing Slide

# Step 1: Attempt to access non-existent slide

officecli get report.pptx /slide[99]/shape[1] --json

Response:

{
  "success": false,
  "error": {
    "error": "Slide 50 not found (total: 8)",
    "code": "not_found",
    "suggestion": "Valid Slide index range: 1-8"
  }
}

The AI agent parses this, extracts the valid range from suggestion, and queries available slides:

# Step 2: List valid slides with depth-limited metadata

officecli get report.pptx /slide --depth 1 --json

Response:

{
  "success": true,
  "data": [
    { "tag": "slide", "path": "/slide[1]" },
    { "tag": "slide", "path": "/slide[2]" },
    { "tag": "slide", "path": "/slide[3]" },
    { "tag": "slide", "path": "/slide[4]" },
    { "tag": "slide", "path": "/slide[5]" },
    { "tag": "slide", "path": "/slide[6]" },
    { "tag": "slide", "path": "/slide[7]" },
    { "tag": "slide", "path": "/slide[8]" }
  ]
}

# Step 3: Retry with validated path

officecli get report.pptx /slide[1]/shape[1] --json

This pattern—attempt, parse error, query valid options, retry—requires no human intervention when the OfficeCLI JSON output schema for AI error recovery is implemented correctly.

Nested Envelope Prevention

A critical implementation detail in ResidentServer.cs (lines 845-863) prevents double-wrapping. Commands that natively produce envelopes (get, add, dump) are returned untouched. Other outputs are wrapped via OutputFormatter.WrapEnvelope*. This ensures you never receive malformed nesting like:

{
  "success": true,
  "data": {
    "success": true,
    "data": { ... }
  }
}

The detection logic checks if the inner result already contains success and data fields before applying the envelope.

Complete Code Examples

Successful Element Retrieval

officecli get deck.pptx /slide[1]/shape[1] --json

{
  "success": true,
  "data": {
    "tag": "shape",
    "path": "/slide[1]/shape[1]",
    "attributes": {
      "name": "TextBox 1",
      "text": "Hello"
    }
  }
}

Validation Error with Corrective Guidance

officecli set deck.pptx '/slide[1]/shape[1]' --prop color=invalidhex --json

{
  "success": false,
  "error": {
    "error": "Invalid color value 'invalidhex'",
    "code": "invalid_value",
    "suggestion": "Use a hex string like #FF0000 or a named color"
  }
}

The suggestion here can be parsed to extract valid formats, or the agent can reference schemas/help/_shared/validation.json for machine-readable constraint definitions.

Warning-Permissive Operations

officecli add deck.pptx / --type shape --prop fill=transparent --json

{
  "success": true,
  "data": {
    "path": "/slide[1]/shape[2]"
  },
  "warnings": [
    {
      "warning": "'transparent' is not a supported fill; defaulting to solid"
    }
  ]
}

Note the exit code 0 despite warnings. Only unsupported warnings trigger exit code 2, allowing agents to distinguish between cosmetic issues and compatibility problems.

Key Source Files for Schema Implementation

File	Lines	Responsibility
src/officecli/ResidentServer.cs	842-870	Envelope construction, exit code mapping, success/warning/error triage
src/officecli/ResidentServer.cs	845-863	Nested envelope detection and wrapping logic
src/officecli/Help/SchemaHelpFlatRenderer.cs	—	Renders --json help documenting per-command envelope contracts
schemas/help/_shared/validation.json	—	Machine-readable error codes and validation flags
README.md	JSON Output Schemas section	Human-readable schema specification with examples

Building Self-Healing Agent Workflows

To maximize the OfficeCLI JSON output schema for AI error recovery:

1. Always use --json for programmatic consumption—never parse stdout/stderr directly
2. Check success before data to avoid null reference errors
3. Implement suggestion parsers for common error codes: not_found, invalid_value, path_syntax, permission_denied
4. Log but don't halt on warnings unless exit code 2 indicates unsupported features
5. Cache schema definitions from schemas/help/_shared/*.json to validate commands before execution

The deterministic contract between OfficeCLI and consuming agents eliminates the fragility of screen-scraping, enabling reliable automation at scale.

Summary

• OfficeCLI's JSON envelope provides deterministic success/failure signaling through success, data, error, and warnings fields
• Exit codes mirror envelope state: 0 for success, 1 for errors, 2 for unsupported warnings
• The error.suggestion field enables automatic error recovery without human intervention
• Nested envelope prevention in ResidentServer.cs ensures clean, predictable output structure
• AI agents can implement self-healing loops: attempt, parse error, query valid alternatives, retry

Frequently Asked Questions

What error codes does OfficeCLI use in the JSON envelope?

OfficeCLI uses descriptive string codes in error.code including not_found for missing elements, invalid_value for malformed properties, path_syntax for malformed XPath-style queries, and permission_denied for locked documents. These codes are defined in schemas/help/_shared/validation.json and documented in the README's JSON Output Schemas section.

How does OfficeCLI prevent double-wrapped JSON envelopes?

Before wrapping output, OfficeCLI checks whether the inner result already contains success and data fields. Commands like get, add, and dump that natively return envelopes are passed through unchanged. This logic resides in ResidentServer.cs lines 845-863, ensuring you never receive nested structures.

Can AI agents trust the suggestion field for automatic correction?

Yes. The suggestion field is machine-generated and follows consistent patterns: range specifications ("Valid Slide index range: 1-8"), format examples ("Use a hex string like #FF0000"), or alternative commands. Agents can parse these with regex or simple string matching to extract actionable values.

What's the difference between warnings and errors in OfficeCLI?

Errors set success: false, populate the error object, and exit with code 1—halting dependent operations. Warnings appear in the warnings array with success: true, indicating the operation completed but with caveats. Exit code 2 specifically indicates unsupported warnings that may affect compatibility.

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