How the OfficeCLI Built-In Help System Works for Property Discovery

The OfficeCLI built-in help system discovers document properties by loading embedded JSON schemas via SchemaHelpLoader and rendering them through SchemaHelpRenderer, which filters properties by verb to show exactly what operations are supported for each element.

The iOfficeAI/OfficeCLI repository provides a discover-first command-line interface for manipulating Office documents. Understanding how its built-in help system handles property discovery allows developers to introspect document models without leaving the terminal, using the same JSON schemas that drive the actual document manipulation logic.

Architecture of the Help System

The help system consists of two core components that transform static JSON resources into interactive documentation.

SchemaHelpLoader

The SchemaHelpLoader class in src/officecli/Help/SchemaHelpLoader.cs serves as the data access layer. It reads embedded schema resources from the assembly using typeof(SchemaHelpLoader).Assembly.GetManifestResourceStream() and deserializes them with System.Text.Json.

This loader provides three key discovery methods:

• ListFormats() – Returns all supported document types (DOCX, PPTX, XLSX)
• ListElements(format) – Enumerates every element available within a format
• LoadSchema(format, element) – Returns a JsonDocument containing the full schema definition for a specific element

The schemas themselves are compiled as embedded resources (e.g., OfficeCli.Schema.docx.json) and contain exhaustive metadata about every property, its type, supported verbs, and validation rules.

SchemaHelpRenderer

Located in src/officecli/Help/SchemaHelpRenderer.cs, the renderer converts the raw JsonDocument into human-readable output. It walks the JSON tree to construct a formatted document that includes:

• Header identifying the format and element
• Description and parent information
• Stable and positional addressing paths
• Supported operations (add, set, get, query, remove)
• Properties with their names, types, supported verbs, aliases, descriptions, and possible values
• Auto-generated usage examples via RenderUsageBlock

Property Discovery Through Verb Filtering

The most powerful feature for property discovery is verb filtering. When you specify an operation in the help command, the system only displays properties that support that specific verb.

When you run:

officecli help set docx paragraph

The Help command (registered in src/officecli/Program.cs) resolves the request and calls SchemaHelpLoader.LoadSchema("docx", "paragraph"). It then passes the resulting JsonDocument to SchemaHelpRenderer.RenderHuman with the verb filter set to set.

Inside RenderHuman, the renderer inspects each property node for a truthy boolean field matching the verb. For example, if a property has "set": true in the schema, it is included; otherwise, it is filtered out. The output header appends (verb-view) to indicate the filtered context.

This mechanism answers the critical development question: "What properties can I modify on this element?" without requiring external documentation.

Rendering Property Details

For each discovered property, the renderer extracts multiple metadata fields from the JSON schema:

• Type – The CLR type or enumeration values
• Verbs – Which operations are valid (shown as [set], [get], etc.)
• Aliases – Shorthand alternatives (e.g., s for style)
• Description – Human-readable explanation
• Examples – Sample values and read-back formats

The RenderUsageBlock method synthesizes concrete CLI examples by consulting the element's paths and addParent fields. This generates syntax like officecli set <file> /body/paragraph[N] --prop style=Heading1 directly from the schema definitions.

Practical Usage Examples

Discover properties for different operations using these commands:

# Show full schema for DOCX paragraph (all properties)

officecli help docx paragraph

# Discover only properties you can SET on a paragraph

officecli help set docx paragraph

# Discover only properties available when ADDING table rows

officecli help add docx tableRow

# Dump raw JSON schema for PPTX slide (advanced scripting)

officecli help --json pptx slide

Typical output for officecli help set docx paragraph:

docx set paragraph
------------------
Read-only container (never created or removed via CLI).

Paths: /body/paragraph[N]  /p[N]

Addressing: path
  role values: doc|header|footer

Operations: set get

Properties (set):
  style   string   [set]   aliases: s
    description: The style name applied to the paragraph.
  indentation   int   [set]  
    description: Indentation in twips.
  ...

Usage:
  officecli set <file> /body/paragraph[N] --prop style=Heading1

Summary

• SchemaHelpLoader reads embedded JSON schemas from assembly resources and provides methods like LoadSchema() and ListElements() to access document metadata.
• SchemaHelpRenderer converts schema documents into human-readable text, filtering properties by verb support (e.g., property.set === true).
• Verb filtering enables targeted property discovery, showing only properties relevant to add, set, get, query, or remove operations.
• Usage generation creates ready-to-run CLI examples by combining path metadata with property definitions from the schema.
• All help content derives from the same JSON schemas used by the execution engine, ensuring documentation accuracy.

Frequently Asked Questions

How does OfficeCLI load the schema definitions used for property discovery?

OfficeCLI loads schemas through the SchemaHelpLoader class, which accesses embedded resource streams via typeof(SchemaHelpLoader).Assembly.GetManifestResourceStream(). These resources contain JSON files (such as OfficeCli.Schema.docx.json) that define every element, property, and supported verb for each document format.

Can I filter the help output to show only properties for a specific operation?

Yes. By including the verb in your help command (e.g., officecli help set docx paragraph), the SchemaHelpRenderer filters the schema to display only properties where the corresponding verb field is true (such as "set": true). The output header indicates this with a (verb-view) suffix.

Where is the help command implemented in the OfficeCLI source code?

The help command is registered in src/officecli/Program.cs. It orchestrates between SchemaHelpLoader (to fetch the schema) and SchemaHelpRenderer (to format the output). The rendering logic specifically lives in src/officecli/Help/SchemaHelpRenderer.cs, which handles the JSON-to-text transformation and usage example generation.

What information is displayed for each discovered property?

Each property shows its name, data type, supported verbs in brackets (e.g., [set] [get]), any aliases (short names), a description, possible values or enums, and concrete examples. The renderer also displays addressing paths and auto-generates usage syntax showing how to reference the property in actual CLI commands.

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