InSpectra.Gen 0.0.61

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, tree layout (one file per command), or hybrid layout (README + one file per command group)
• 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:
    mode: dotnet
    project: src/MyCli       # path to your .csproj
    format: markdown         # or html

See GitHub Action for full documentation, including the auto-installed InSpectra.Cli package and SDK detection.

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 project on disk (dotnet mode)

# Point at a .csproj or directory containing one — InSpectra runs
# `dotnet run --project <PROJECT> -- cli opencli` for you.
inspectra render dotnet markdown src/MyCli \
  --configuration Release \
  --no-build \
  --layout tree \
  --out-dir ./docs

inspectra render dotnet html src/MyCli \
  --configuration Release \
  --no-build \
  --with-xmldoc \
  --out-dir ./docs

This is the most convenient option when you're iterating on the CLI source — no manual export, no published tool, no pre-built binary.

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.

Looking for a deeper guide? See docs/CI/ for the full integration manual: usage patterns, inputs reference, and end-to-end recipes (Pages, docs PR, drift check, release asset).

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

Generating docs from a .NET project on disk (dotnet mode)

When you want docs generated from the current source (no published NuGet tool, no pre-built binary), point the action at a .csproj. The action then:

1. Detects the project's <TargetFramework> and installs the matching .NET SDK (skipping versions already on the runner).
2. Adds a <PackageReference Include="InSpectra.Cli" /> for you so you don't have to maintain the dependency by hand. Skipped if already referenced.
3. Runs dotnet run --project <csproj> -- cli opencli to extract the spec and renders it.

steps:
  - uses: actions/checkout@v4

  - uses: JKamsker/InSpectra@v1
    with:
      mode: dotnet
      project: src/MyCli              # path to .csproj or directory
      configuration: Release
      no-build: 'false'               # set true if you build in a previous step
      format: markdown                # html / markdown / markdown-monolith
      output-dir: docs/cli

actions/setup-dotnet and dotnet tool install are no longer needed in the caller workflow — the action handles both.

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

Action output

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:
          mode: dotnet
          project: src/MyCli
          configuration: Release
          output-dir: _site

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

End-to-end example: open a PR with regenerated Markdown

The pattern for "always-fresh CLI reference checked into the repo" is the combination of mode: dotnet and peter-evans/create-pull-request:

name: Update CLI Docs

on:
  push:
    branches: [main]
    paths: ['src/MyCli/**']
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

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

      - uses: JKamsker/InSpectra@v1
        with:
          mode: dotnet
          project: src/MyCli
          format: markdown
          output-dir: docs/cli

      - uses: peter-evans/create-pull-request@v6
        with:
          branch: chore/update-cli-docs
          title: 'docs: regenerate CLI reference'
          add-paths: docs/cli

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:

CLI Reference

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

Markdown

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

Markdown supports:

• --out <FILE> for single-file output
• --out-dir <DIR> with --layout tree or --layout hybrid
• --layout single|tree|hybrid
• --split-depth <N> with --layout hybrid (defaults to 1) — controls the depth at which per-group Markdown files are emitted. Depth 1 produces README.md plus one file per top-level group; depth 2 also emits a file per second-level group; and so on.

HTML

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

Dotnet mode

render dotnet markdown <PROJECT> [OPTIONS]
render dotnet html <PROJECT> --out-dir <DIR> [OPTIONS]

Resolves <PROJECT> to a .csproj / .fsproj / .vbproj (a directory with exactly one is also accepted) and runs dotnet run --project <PROJECT> [build flags] -- cli opencli under the hood. Reuses every option from render exec plus the dotnet-specific build flags:

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:

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

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.

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