InSpectra

Turn any CLI's OpenCLI spec into beautiful, navigable documentation — Markdown or interactive HTML — in a single command.

Website: inspectra.kamsker.at | Live examples | Try it

---

Table of Contents

• Features
• Install
• Quick Start
• GitHub Action
• Reusable Workflow
• CLI Reference
• HTML Viewer
• Architecture
• Project Layout
• Contributing
• Examples

Features

• Markdown output — GitHub-friendly single file or tree layout (one file per command)
• Interactive HTML viewer — relocatable SPA bundle with sidebar navigation, search, dark/light theme, and deep-link hash routing
• Command composer — interactively build CLI invocations from documented options and arguments
• Command palette — fuzzy search across all commands (Ctrl+K)
• NuGet browser — search and explore indexed .NET CLI tool packages
• XML enrichment — additive metadata from XML docs, only fills missing descriptions
• Validation first — broken specs fail early, before any rendering
• Self-documentation — InSpectra can generate its own docs
• GitHub Action — one-step CI integration for any .NET CLI tool
• Secure by default — generated pages expose only the features you explicitly enable

Install

As a .NET global tool

dotnet tool install -g InSpectra.Gen

This installs the inspectra command globally.

As a GitHub Action

- uses: JKamsker/InSpectra@v1
  with:
    cli-name: mycli

See GitHub Action for full documentation.

Quick Start

Prerequisites

• .NET 10 SDK
• Node.js (only needed for local frontend builds, CI, and dotnet pack / dotnet publish)

Render from a live CLI (exec mode)

# Generate an interactive HTML documentation site
inspectra render exec html mycli --out-dir ./docs

# Generate Markdown with XML enrichment
inspectra render exec markdown mycli --with-xmldoc --out docs.md

Render from a saved OpenCLI JSON file (file mode)

# HTML bundle
inspectra render file html opencli.json --out-dir ./docs

# Markdown with XML enrichment
inspectra render file markdown opencli.json \
  --xmldoc xmldoc.xml \
  --out docs.md

Render from a .NET tool

# Install the target CLI and generate docs
dotnet tool install -g JellyfinCli
inspectra render exec html jf --with-xmldoc --out-dir ./jellyfin-docs

Open ./jellyfin-docs/index.html in a browser. The bundle is relocatable because the viewer is built with base: "./".

GitHub Action

The JKamsker/InSpectra@v1 action generates interactive CLI documentation in your CI pipeline.

Basic usage (exec mode)

steps:
  - uses: actions/checkout@v4

  - uses: JKamsker/InSpectra@v1
    with:
      cli-name: mycli

Generating docs for a .NET tool

steps:
  - uses: actions/checkout@v4

  - uses: JKamsker/InSpectra@v1
    with:
      cli-name: mycli
      dotnet-tool: MyCompany.MyCli    # installs via dotnet tool install -g

File mode (from saved spec)

steps:
  - uses: actions/checkout@v4

  - uses: JKamsker/InSpectra@v1
    with:
      mode: file
      format: html
      opencli-json: docs/opencli.json
      xmldoc: docs/xmldoc.xml

Markdown output

- uses: JKamsker/InSpectra@v1
  with:
    cli-name: mycli
    format: markdown            # tree layout (one file per command)

- uses: JKamsker/InSpectra@v1
  with:
    cli-name: mycli
    format: markdown-monolith   # single file

Action inputs

Input	Default	Description
mode	exec	exec (invoke a live CLI) or file (from saved opencli.json)
format	html	html, markdown (tree), or markdown-monolith (single file)
cli-name		CLI executable name or path (exec mode)
dotnet-tool		NuGet package to dotnet tool install -g (exec mode)
dotnet-tool-version		Version constraint for the dotnet tool
opencli-json		Path to opencli.json (file mode)
xmldoc		Path to xmldoc.xml (file mode)
output-dir	inspectra-output	Directory where rendered output is written
label		Custom label shown in the viewer header (e.g. v1.2.3)
extra-args		Additional flags forwarded to the inspectra CLI
inspectra-version	latest	InSpectra.Gen NuGet tool version
dotnet-version	10.0.x	.NET SDK version to install
dotnet-quality	stable	.NET SDK quality channel (preview for pre-release)
opencli-args		Override the OpenCLI export arguments
xmldoc-args		Override the xmldoc export arguments
timeout		Timeout in seconds for each export command (exec mode)

Action output

Output	Description
output-dir	Path to the rendered output directory

End-to-end example: deploy to GitHub Pages

name: Deploy CLI docs

on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: JKamsker/InSpectra@v1
        with:
          cli-name: mycli
          dotnet-tool: MyCompany.MyCli
          output-dir: _site

      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

Reusable Workflow

For convenience, a reusable workflow wraps the action with checkout, tool install, and artifact upload:

jobs:
  docs:
    uses: JKamsker/InSpectra/.github/workflows/inspectra-generate.yml@v1
    with:
      cli-name: mycli
      dotnet-tool: MyCompany.MyCli

The workflow accepts the same inputs as the action, plus:

Input	Default	Description
setup-command		Custom shell command to make the CLI available on PATH
artifact-name	inspectra-docs	Name of the uploaded artifact

CLI Reference

inspectra render [file|exec] [markdown|html] [OPTIONS]

Markdown

render file markdown <OPENCLI_JSON> [OPTIONS]
render exec markdown <SOURCE> [OPTIONS]

Markdown supports:

• --out <FILE> for single-file output
• --out-dir <DIR> with --layout tree
• --layout single|tree

HTML

render file html <OPENCLI_JSON> --out-dir <DIR> [OPTIONS]
render exec html <SOURCE> --out-dir <DIR> [OPTIONS]

HTML uses bundle-directory output only:

• --out-dir <DIR> is required
• --out is rejected
• --layout is rejected
• machine-readable JSON reports layout: "app"

Self-Documentation

render self --out-dir <DIR> [OPTIONS]

Generates InSpectra's own documentation by self-invoking cli opencli and cli xmldoc, then rendering all formats into a single output directory. This is the canonical way to regenerate docs/inspectra-gen/.

The output directory will contain:

• opencli.json — the raw OpenCLI export (clean JSON, free of Spectre.Console line-wrapping artifacts)
• xmldoc.xml — the raw XML documentation export
• tree/ — Markdown tree layout
• html/ — HTML app bundle

Additional options:

Option	Description
--skip-markdown	Skip Markdown tree generation
--skip-html	Skip HTML bundle generation

All HTML feature flags (--show-home, --no-composer, etc.) and common options (--include-hidden, --include-metadata, --overwrite) are supported.

# Regenerate docs/inspectra-gen
inspectra render self --out-dir docs/inspectra-gen --overwrite

Common Options

Option	Description
--xmldoc <PATH>	XML enrichment file for render file ...
--with-xmldoc	Also invoke cli xmldoc in exec mode
--source-arg <ARG>	Argument passed to the source CLI
--opencli-arg <ARG>	Override the OpenCLI export invocation
--xmldoc-arg <ARG>	Override the xmldoc invocation
--include-hidden	Include hidden commands and options
--include-metadata	Include metadata sections in rendered output
--overwrite	Overwrite existing output
--dry-run	Preview output without writing files
--json	Emit machine-readable render results
--timeout <SECONDS>	Exec-mode timeout

HTML Feature Flags

When rendering HTML bundles, the following flags control which UI features are available to the end user. These flags only apply to render file html and render exec html.

By default, statically generated pages are locked down: only the inline command viewer and composer are active. Features like the home screen, NuGet browser, file upload, URL loading, and theme switching must be explicitly opted in. This "secure by default" approach ensures generated documentation pages expose exactly the features you choose.

Flag	Default	Description
--show-home	off	Show the Home button in the toolbar. Required for --enable-nuget-browser and --enable-package-upload.
--no-composer	off	Hide the Composer panel and its toolbar toggle.
--no-dark	off	Disable the dark theme and force light mode. Cannot be combined with --no-light.
--no-light	off	Disable the light theme and force dark mode. Cannot be combined with --no-dark.
--enable-url	off	Allow loading OpenCLI specs from URL query parameters (?opencli=, ?xmldoc=, ?dir=).
--enable-nuget-browser	off	Enable the NuGet package browser on the home screen. Requires --show-home.
--enable-package-upload	off	Enable the file upload drop zone on the home screen. Requires --show-home.

Validation rules:

• --no-dark and --no-light cannot both be set (at least one theme must be available).
• --enable-nuget-browser requires --show-home (the browser is accessed from the home screen).
• --enable-package-upload requires --show-home (the upload drop zone is on the home screen).

Examples:

Minimal static page (defaults):

inspectra render file html mycli.json --out-dir ./docs

Full-featured hosted viewer with all interactive features:

inspectra render file html mycli.json --out-dir ./docs \
  --show-home \
  --enable-url \
  --enable-nuget-browser \
  --enable-package-upload

Read-only dark-mode documentation without the composer:

inspectra render file html mycli.json --out-dir ./docs \
  --no-composer \
  --no-light

Light-mode-only page with file upload but no NuGet browser:

inspectra render file html mycli.json --out-dir ./docs \
  --show-home \
  --enable-package-upload \
  --no-dark

How it works: Feature flags are serialized into the HTML bootstrap payload (the <script id="inspectra-bootstrap"> JSON block). The viewer reads them at startup and conditionally renders UI elements. When running the viewer in development mode (no bootstrap), all features are enabled by default. When an older bootstrap without the features key is loaded, the viewer falls back to secure defaults (everything off except both themes).

HTML Viewer (InSpectraUI)

The HTML renderer copies src/InSpectra.UI/dist/** and patches index.html with a bootstrap payload.

Boot Modes

The bundled viewer supports three boot paths:

1. Inline bootstrap (default for generated pages): The full OpenCLI document is embedded in the HTML as a JSON payload. The page is self-contained and works offline.
2. URL-driven loading: Query parameters ?opencli=<url>, ?xmldoc=<url>, or ?dir=<url> point the viewer at remote files. Only active when --enable-url is set (or in development mode).
3. Manual import: Users drop or pick opencli.json and optional xmldoc.xml from disk. Only shown when --enable-package-upload is set (or in development mode).

Viewer Features

• Command tree with sidebar navigation, search filtering (Ctrl+F), and deep-link hash routing
• Command palette (Ctrl+K) for quick fuzzy search across all commands
• Composer panel for interactively building CLI invocations from documented options and arguments (toggleable, hideable via --no-composer)
• Dark/light theme with toggle button and localStorage persistence (lockable to one theme via --no-dark or --no-light)
• NuGet browser for searching and exploring indexed .NET CLI tool packages (opt-in via --enable-nuget-browser)
• Overview panel showing root-level arguments, options, and command summary
• Recursive option inheritance display
• Metadata sections (when --include-metadata is set)

URL Parameters

?dir=<url> resolves:

• <dir>/opencli.json
• optional <dir>/xmldoc.xml

Missing inferred xmldoc.xml is non-fatal.

Architecture

Data flow

OpenCLI JSON ──┐
XML metadata ──┴─> validate -> enrich -> normalize -> render -> write

HTML runtime model

• v1 uses raw opencli.json plus optional xmldoc.xml as the canonical browser input
• the .NET HTML pipeline keeps the existing acquisition and validation flow
• injected HTML output defaults to inline bootstrap mode
• internal links-mode support remains available for hosted scenarios

Bundle resolution

At runtime, HTML assets are resolved in this order:

1. packaged InSpectra.UI/dist beside the installed tool
2. repo-local src/InSpectra.UI/dist
3. repo-local npm ci plus npm run build if dist is missing and npm is available
4. otherwise a clear error telling you how to build the frontend

dotnet pack and dotnet publish do not run npm implicitly. They fail if src/InSpectra.UI/dist/index.html is missing.

Project Layout

src/InSpectra.Gen/               CLI tool and render services
src/InSpectra.UI/                Vite + React + TypeScript viewer app
tests/InSpectra.Gen.Tests/       xUnit test suite
docs/                            Website and self-generated docs
examples/                        Example renders (Jellyfin, JDownloader)
.github/actions/render/          GitHub Action (composite)
.github/workflows/               CI, Pages deployment, reusable workflow

Contributing

Build from source

# Build the viewer bundle
cd src/InSpectra.UI
npm ci && npm test && npm run build
cd ../..

# Build and test the .NET tool
dotnet build InSpectra.Gen.sln --configuration Release
dotnet test InSpectra.Gen.sln --configuration Release

Testing

# Frontend tests
cd src/InSpectra.UI && npm test

# Backend tests
dotnet test InSpectra.Gen.sln --configuration Release

Coverage includes:

• frontend bootstrap precedence and import flows
• XML enrichment and normalization behavior
• HTML output contract and bootstrap injection
• bundle resolution order
• Markdown output paths and layout handling

CI

CI builds the frontend before running the .NET test and packaging flow. Each build produces a versioned NuGet package (0.0.<build-number>) uploaded as a CI artifact. GitHub Pages publishes HTML examples as bundle directories at inspectra.kamsker.at.

Examples

Example	Source	Live
InSpectra (self-doc)	docs/inspectra-gen	View
Jellyfin CLI	examples/jellyfin-cli	View
JDownloader RemoteCli	examples/jdownloader-remotecli	View