herald-help

Themed CLI help pages powered by herald typography.

When to use | Installation | Quick Start | Styles | Types | Rendering | Options | Examples | Structure

herald-help generates themed CLI help pages through herald's typography system. Works with cobra, urfave/cli, kong, and stdlib flag.

When to use herald-help

Cobra, Kong, and urfave/cli all generate plain-text help output with basic formatting. herald-help takes a different approach. Paired with herald, it gives you themed help pages that match the rest of your CLI output. Use it when:

• You want one theme for your entire CLI - pick a built-in theme (Dracula, Catppuccin, Base16, Charm) or define your own, and help pages use it automatically.
• You need structured, composable help - Render returns a plain string you can pass to herald's Compose alongside other output.
• You want framework-agnostic help rendering - define your help structure once with Command, then use adapters to convert from any CLI framework.

Installation

Requires Go 1.25+.

go get github.com/indaco/herald-help@latest

Quick Start

Framework adapters are sub-modules — each has its own go.mod, so importing one does not pull in the others.

The stdlib flag adapter (FromFlagSet) is included in the core module — no extra install needed.

Standalone

See examples/compact/000_manual for a full runnable example. For stdlib flag integration, see examples/compact/001_flag.

[!NOTE] The Go module path is github.com/indaco/herald-help but the package name is heraldhelp. Use an import alias: heraldhelp "github.com/indaco/herald-help".

import (
    "fmt"
    "github.com/indaco/herald"
    heraldhelp "github.com/indaco/herald-help"
)

ty := herald.New()

cmd := heraldhelp.Command{
    Name:        "myapp",
    Synopsis:    "myapp [flags] <command>",
    Description: "A sample application.",
    Flags: []heraldhelp.Flag{
        {Long: "--output", Short: "-o", Type: "string", Default: "stdout", Desc: "Output destination"},
        {Long: "--verbose", Short: "-v", Type: "bool", Default: "false", Desc: "Enable verbose output"},
    },
    Commands: []heraldhelp.CommandRef{
        {Name: "serve", Desc: "Start the server"},
        {Name: "build", Desc: "Build the project"},
    },
    Footer: heraldhelp.FormatVersion("myapp", "1.0.0"),
}

fmt.Println(heraldhelp.Render(ty, cmd))

With cobra

See examples/compact/002_cobra for a full runnable example.

import (
    "github.com/indaco/herald"
    heraldhelp "github.com/indaco/herald-help"
    heraldcobra "github.com/indaco/herald-help/cobra"
    "github.com/spf13/cobra"
)

rootCmd.SetHelpFunc(func(cmd *cobra.Command, args []string) {
    ty := herald.New()
    heraldhelp.RenderTo(cmd.OutOrStdout(), ty, heraldcobra.FromCobra(cmd))
})

With urfave/cli

See examples/compact/003_urfave for a full runnable example.

import (
    "io"
    heraldhelp "github.com/indaco/herald-help"
    heraldurfave "github.com/indaco/herald-help/urfave"
    "github.com/urfave/cli/v3"
)

cli.HelpPrinter = func(w io.Writer, _ string, data any) {
    cmd, ok := data.(*cli.Command)
    if !ok {
        return
    }
    ty := herald.New()
    heraldhelp.RenderTo(w, ty, heraldurfave.FromUrfave(cmd))
}

With kong

See examples/compact/004_kong for a full runnable example.

import (
    heraldhelp "github.com/indaco/herald-help"
    heraldkong "github.com/indaco/herald-help/kong"
)

parser, _ := kong.New(&cli,
    kong.Help(func(_ kong.HelpOptions, ctx *kong.Context) error {
        ty := herald.New()
        return heraldhelp.RenderTo(os.Stdout, ty, heraldkong.FromKong(ctx.Kong))
    }),
)

Styles

herald-help supports four rendering styles, controlled by the WithStyle option.

StyleCompact (default)	StyleGrouped
StyleRich	StyleMarkdown

To use a non-default style, pass WithStyle to Render or RenderTo:

// Rich style with bordered tables
heraldhelp.RenderTo(os.Stdout, ty, cmd, heraldhelp.WithStyle(heraldhelp.StyleRich))

// Grouped style with fieldset borders
heraldhelp.RenderTo(os.Stdout, ty, cmd, heraldhelp.WithStyle(heraldhelp.StyleGrouped))

// Markdown output — pipe to glow or render via herald-md
md := heraldhelp.Render(ty, cmd, heraldhelp.WithStyle(heraldhelp.StyleMarkdown))

Types

Rendering

Each Command field maps to a section in the output. The exact herald method used depends on the active style (see Styles above). The table below shows the StyleRich mapping as reference:

Flags are displayed in GNU-style format (-o, --output). Environment variables are shown inline ([$PORT]).

Functions:

• Render(ty, cmd, opts...) string - render to string
• RenderTo(w, ty, cmd, opts...) error - render to io.Writer
• FormatVersion(name, version) string - format a version footer string

Options

Examples

Runnable examples are in the examples/ directory, organized by style. The 0xx examples run directly; the adapter examples (002+) are separate modules.

Compact style (default — uppercase headings, indented two-column lists, no borders):

Rich style (decorated headings, bordered tables, code blocks):

Grouped style (each section in a bordered fieldset):

Markdown style (valid Markdown text, pipeable to glow/bat):

Repository structure

This is a multi-module Go repository. The core module lives at the root; framework adapters are sub-modules in their own directories, each with a separate go.mod:

herald-help/
  go.mod            # github.com/indaco/herald-help (core types + renderer + flag adapter)
  cobra/go.mod      # github.com/indaco/herald-help/cobra
  urfave/go.mod     # github.com/indaco/herald-help/urfave
  kong/go.mod       # github.com/indaco/herald-help/kong
  examples/
    compact/        # StyleCompact examples (default; 002-004 are separate modules)
    rich/           # StyleRich examples (002-004 are separate modules)
    grouped/        # StyleGrouped examples
    markdown/       # StyleMarkdown examples (001 is a separate module with herald-md)

Use just test-all, just lint-all, just check-all to run across all modules.

License

This project is licensed under the MIT License - see the LICENSE file for details.