CLI Interactive Help Menu

Browse command options while typing. Insert a flag. Keep control of execution.

A Linux Bash prototype for terminal users who need option descriptions without abandoning an unfinished command. Alt-H opens searchable, categorized help; selecting an option returns to the command line with that flag inserted. The pending command runs only after a separate, ordinary Enter at the Bash prompt.

Get started · Browser controls · Scan and review · Documentation

Browse categories → search → insert options and values → continue editing. The 31-second loop shows rsync's nine categories and ls's twelve-option Display list, including pane focus, scrolling, required arguments, and cancellation. Static rsync browser · Scrolled ls options · Assembled rsync command

What it provides

Capability	End-user result
Help alongside command entry	Search options, scroll categories, and read descriptions before selecting a flag
Prefixes and structured syntax	Browse documented commands behind supported prefixes, Python modules, keyword arguments, and concrete stream selectors
Insertion without execution	Continue editing arguments after selection; cancel to retain the original command and cursor
Help for installed tools	Discover options from help output and local manuals, with Git/Docker subcommand support and loadable drivers
Reusable help collections	Import a manual or scan installed commands in bulk, with a report of successes, failures, and review needs
Guided corrections	Edit options, categories, and driver settings through terminal forms, then preview and save with backups
Configurable controls	Customize the launch shortcut and browser navigation keys
Passive troubleshooting	Inspect configuration and command recognition without help probes or disclosure of pending operand values
Verified release updates	Check GitHub releases, preserve custom settings during upgrades, and resolve conflicts through guided review

flowchart LR
    A[Type a command] -->|Alt-H| B[Browse categories and search options]
    B -->|Search with / then Enter| F[Filtered options]
    F -->|Enter selects a flag| C[Continue editing the command]
    B -->|Enter selects a flag| C
    B -->|Cancel| D[Original command and cursor retained]

Loading

The browser includes curated help for everyday Linux tools, service and network inspection, language tooling, containers, cloud CLIs, Git families, and embedded development. Ordinary curated profiles work without installed targets. Guarded vendor/version profiles require identity verification; generated help remains inferred and may require corrections.

The third-party compatibility matrix covers 162 command paths across 73 executable names. Included drivers enable nested command routes; the guide lists every route, activation instructions, version constraints, and verification limits. Prefix and structured-argument support adds sudo/env/command chains, selected-interpreter python -m pip and python -m pytest, ip keywords, FFmpeg stream selectors, and esptool address/file pairs. Help selection continues to edit the buffer without executing it.

Get started

Requirements:

• Linux, Bash 4.4+, and Python 3.10+ with the standard-library curses module.
• A UTF-8 locale and a terminal at least 60 columns × 16 rows.
• The standard Linux stty utility for terminal-size detection and resize recovery.
• Linux man-db and local manual pages for manual-based discovery, importing installed pages, and bulk scanning. Text-file imports do not require man.

From the repository directory, install for the current user and load the browser:

bash install.sh
source "${XDG_DATA_HOME:-$HOME/.local/share}/cli-interactive-help/bash/interactive-help.bash"

1. Type rsync --ar without executing it.
2. Press Alt-H, browse to --archive, and press Enter.
3. Continue editing the resulting rsync --archive command line.

Arrow keys navigate the menu; / searches; Escape or Ctrl-C cancels. If Alt-H is unavailable, press Escape followed by h. The installer adds a marked block to .bashrc and backs up existing contents. Use bash install.sh --no-rc to skip startup registration, or bash uninstall.sh to remove the default installation. Edited files and custom collections are retained.

To upgrade an existing installation, run bash update.sh from the new source directory. Custom settings and edited files are preserved; conflicts include incoming copies for manual merging and a full backup. The interactive update reviewer compares conflicts and lets each file be kept, replaced, or merged, with backups before saving. Guided editing accepts or rejects individual changed blocks without an external editor.

The GitHub release updater checks and verifies published packages before upgrading. Run bash update-from-github.sh --check to inspect the stable channel, or add --prerelease to include alpha releases. Run without --check to upgrade; conflicts open the guided reviewer in an interactive terminal.

The current checkout is 0.1.2-alpha, prepared as an unpublished local candidate. The release guide describes its installer, Linux launcher, source/runtime archives, checksums, and source provenance. The preserved 0.1.1-alpha packages contain an older snapshot. Use the checkout or a locally built candidate for the functionality described here; a GitHub release check does not obtain unpublished changes.

See installation, updates, and removal for custom paths and recovery. Browser controls covers shortcuts, Vi keymaps, configuration, and loading directly from a checkout without installing.

Build and refine a help collection

The scanner reads installed manuals and produces editable help plus a report. The reviewer provides guided corrections and a preview of the actual help menu. Run these commands from the repository directory:

python3 cli_help/main.py --scan-installed --limit 100 \
  --output-dir "$HOME/.config/cli-help/scanned"

python3 cli_help/main.py --review-report \
  "$HOME/.config/cli-help/scanned/scan-report.json"

In a review entry, o edits options, c edits categories, and d edits driver settings. p previews the menu and s saves validated changes with backups. JSON editing is optional. Original scan findings remain available.

Guided option editing in an example collection; changes require explicit saving.

After inspecting a collection with successfully generated entries, activate it:

export CLI_HELP_PROFILES="$HOME/.config/cli-help/scanned/profiles"
export CLI_HELP_DRIVERS="$HOME/.config/cli-help/scanned/drivers"
python3 cli_help/main.py --check

• Bulk scanning and report interpretation covers filters, repeated scans, partial results, and activation.
• Guided review and correction covers forms, preview, saving, and recovery.
• Importing a single manual supports installed pages, rendered text, and local manual files.

Compatibility and execution boundaries

Option selection never executes the pending command. Automatic discovery can run a separate help invocation of the installed program. Arbitrary programs may have startup side effects. Discovery limits are not a sandbox.

To obtain dynamic help without invoking target programs:

export CLI_HELP_DISCOVERY=man

This mode uses the manual renderer and requires an installed executable with a usable local manual. CLI_HELP_DISCOVERY=off restricts browsing to static profiles. Bulk scanning and manual import do not invoke target programs; review preview performs no help discovery.

The prototype supports simple commands with balanced quoting. Pipelines, redirection, shell substitutions, unsupported prefix forms, and shell aliases or functions are not resolved. Bounded sudo/env/command chains and Python module forms are supported. Generated help can omit unusual option syntax; subcommand support depends on available profiles and drivers.

Discovery and execution boundaries describes these limits in full. Recorded validation identifies the tested environment and remaining compatibility limits.

Further documentation

Purpose	Guide
Set up the browser and customize controls	Usage and keybindings
Add or maintain command compatibility	Profiles and drivers
Enable third-party command paths and run compatibility checks	Third-party compatibility matrix
Inspect configuration and command recognition without probes	Passive diagnostics and troubleshooting
Understand discovery, caching, and safe insertion	Discovery and safety
Import, scan, and correct documentation	Collection workflows
Inspect the implementation or run tests	Architecture and validation

The documentation index provides the complete topic map. The media capture guide describes the demonstrations and their regeneration.