clap-help

clap-help is a Rust library that renders the --help message for clap-based command-line applications in a far more compact and readable form than clap’s built-in renderer. It produces layouts that are width-aware, typically two to three times shorter than the vanilla output, and arranges options into a balanced table optimized for the terminal’s width.

Beyond compactness, clap-help interprets your introduction text and per-option documentation as Markdown, so help screens can include lists, tables, and code blocks. It automatically picks a skin suited to light or dark terminals via terminal-light, renders through termimad, and lets you customize, reorder, remove, or add help sections through templates.

What You Get

• A compact, width-aware help layout typically 2-3x shorter than clap’s default
• Options rendered in a balanced table sized to the terminal width
• Markdown interpretation of the intro text and per-option documentation
• Automatic light/dark terminal skin selection with full termimad customization
• Customizable section templates you can reorder, remove, or extend

Common Use Cases

• Making a clap CLI’s —help output more readable and less sprawling
• Adding a Markdown introduction with examples, lists, or tables to a help screen
• Matching help styling to the rest of a themed terminal application
• Restructuring help into custom sections beyond clap’s fixed layout

Under The Hood

Architecture - The crate is small: lib.rs exposes a Help type built from a clap Command, and printer.rs handles the actual rendering. It reads clap’s argument metadata, groups options into a table whose column widths are computed from the terminal size, and feeds section text (intro, options, custom sections) through termimad’s Markdown renderer. Section templates drive what is printed and in what order, so the layout is data-driven rather than hard-coded.

Tech Stack - Pure Rust (edition 2021, MSRV 1.65). It depends on clap 4.6 (with derive and cargo features) for the command model, termimad for Markdown-to-terminal rendering, and terminal-light to detect whether the terminal is light or dark for skin selection.

Code Quality - A focused, single-author project (32 commits) that is nonetheless actively maintained and used in production by the author’s other tools (bacon, broot ecosystem). The scope is intentionally narrow, which keeps the codebase small and comprehensible; there is no subcommand support yet, a known limitation stated in the README.

API Design - Ergonomic for its purpose: you disable clap’s help flag, construct a Help printer, optionally set an intro and a custom skin/templates, and print. The Markdown-based customization is expressive without requiring you to write rendering code, and defaults produce a good result out of the box, so simple adoption is nearly drop-in.