Understanding the Schema-Driven Help System in OfficeCLI: Architecture and Access Methods

The OfficeCLI help system uses JSON-Schema files to generate documentation dynamically, accessible via officecli help <format> <element> and the --json flag for programmatic consumption.

The OfficeCLI repository implements a schema-first help architecture where documentation and validation logic share the same source of truth. Rather than hardcoding help text, the CLI derives all element descriptions, property lists, and usage examples directly from JSON-Schema definitions. This ensures that help output automatically stays synchronized with the actual capability of each command handler.

How the Schema-Driven Help System Works

The help system operates through a three-stage pipeline that transforms static schema files into either human-readable documentation or machine-readable JSON.

Stage 1: Schema Discovery and Mapping

When you invoke the help command, the CLI first resolves the canonical schema path. The mapping between command arguments and file locations is defined in schemas/README.md, which documents the directory structure for all supported formats:

• Word documents (.docx): schemas/help/docx/
• Excel workbooks (.xlsx): schemas/help/xlsx/
• PowerPoint presentations (.pptx): schemas/help/pptx/

The CLI normalizes format aliases during this stage. For example, word resolves to docx before locating the schema file.

Stage 2: Schema Parsing and Rendering

The selected JSON-Schema file undergoes two possible render paths based on your flags:

Default path (human-readable): The parser traverses the schema object and converts property definitions into formatted output. Each property displays its name, type, default value, accepted values, and inline examples. This rendering logic respects schema annotations such as description, enum, and default fields.

JSON path (machine-readable): When --json is present, the CLI bypasses rendering and returns the parsed schema object directly. This preserves all metadata—including $ref resolutions and validation constraints—for downstream consumption.

Stage 3: Contract Validation

The repository maintains contract tests that verify every schema claim against the actual handler implementation. As documented in plugins/plugin-protocol.md, these tests validate that operations marked as supported in the schema (add, set, get, readback) execute correctly against real Office documents. This guarantees that help output never drifts from actual functionality.

Accessing the Schema-Driven Help System

The help system exposes two primary interfaces depending on your use case: interactive terminal exploration and programmatic schema retrieval.

Interactive Documentation Mode

Display formatted, human-readable documentation for any supported element:

officecli help <format> <element>

Common examples:

# View all paragraph properties and formatting options

officecli help docx paragraph

# Explore Excel chart configuration options

officecli help xlsx chart

# Inspect PowerPoint shape manipulation capabilities

officecli help pptx shape

This mode renders property tables with type information, defaults, and usage examples suitable for quick reference during development.

Programmatic Schema Export

Retrieve the raw JSON-Schema for integration with scripts, agents, or custom tooling:

officecli help <format> <element> --json

Practical integration patterns:

# Extract specific property definitions with jq

officecli help xlsx conditionalformatting --json | jq '.properties.rules'

# Save schema to file for offline validation

officecli help docx table --json > docx-table-schema.json

# Validate user input against schema in a shell script

SCHEMA=$(officecli help pptx slide --json)

# Apply validation logic using $SCHEMA

Global Help and Command Enumeration

Running help without format or element arguments lists all available verbs and global options:

officecli help

This displays every supported operation including add, set, get, query, remove, and validate, along with flags that apply across all commands.

Key Schema Files and Their Roles

File Path	Purpose
schemas/README.md	Documents the overall schema directory structure and mapping conventions
main/SKILL.md	Defines the help verb interface and provides usage examples
schemas/help/docx/paragraph.json	Schema definition for Word paragraph elements
schemas/help/xlsx/chart.json	Schema definition for Excel chart elements
schemas/help/pptx/shape.json	Schema definition for PowerPoint shape elements
plugins/plugin-protocol.md	Specifies contract testing requirements between schemas and implementations

Summary

• Schema-first design: Help content derives from JSON-Schema files, eliminating documentation drift
• Dual output modes: Human-readable tables via default invocation, raw JSON via --json flag
• Automatic synchronization: Contract tests ensure schema claims match handler implementations
• Alias normalization: Format names like word resolve to canonical identifiers (docx) before schema lookup
• Extensible architecture: Adding new elements requires only new schema files, no code changes to the help system itself

Frequently Asked Questions

How does OfficeCLI ensure help output stays accurate with code changes?

The repository runs contract tests that execute every operation declared in a schema against real Office document handlers. These tests verify that properties marked as supported actually function as documented, catching discrepancies during CI rather than at runtime.

Can I use the schema output to build my own validation layer?

Yes. The --json flag returns complete JSON-Schema definitions that include type constraints, enum values, required fields, and nested property structures suitable for validation libraries like ajv, jsonschema, or native implementations in Python, Go, or other languages.

What happens if I request help for an unsupported format or element?

The CLI performs schema path resolution against the canonical mapping in schemas/README.md. If no matching schema file exists, the command returns a clear error indicating that the format or element is not recognized, rather than generating invalid or incomplete documentation.

Does the help system support custom schema extensions or plugins?

The schema directory structure documented in schemas/README.md follows a predictable convention. While the core repository defines standard Office formats, the plugin protocol in plugins/plugin-protocol.md implies that consistent schema placement enables the same help generation pipeline to work for extended functionality.

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