halp: finding the right help flag for any command line tool

The problem halp is solving

The premise is in the README's own scenario. A command line tool that does not follow the conventions will reject the obvious flags, printing unknown flag errors for each attempt, and the user ends up brute-forcing their way to the right invocation. The example shows the frustration: a version flag rejected, a capital V rejected, a help flag rejected, and then a mistyped command name producing a not found message from bash itself.

halp exists to skip that. It aims to help find the correct arguments for command line tools by checking a predefined list of commonly used options and flags. The list for help is --help, -h, help and -H. The list for version information is --version, -v, version and -V.

The behaviour is straightforward. If one of these arguments succeeds, with exit code 0, halp prints the output and exits. That is the whole contract, and the exit code check is the part that makes it reliable: a tool that accepts a flag and then fails is not treated as a success, so halp keeps looking instead of printing an error message as if it were help.

Because the check is on the exit status rather than on the output text, halp does not need to know anything about the tool it is inspecting. It runs a command, looks at how it exited, and reports. That is why it works on anything, including tools it has never heard of.

The plz subcommand and the manual page fallback

The flags cover the common case, but the README is candid that sometimes you really need help. The plz subcommand prompts a selection between showing the man page, which runs man(1), and showing a cheat sheet, which goes through cheat.sh.

So there are two tiers. The default behaviour is a fast, non-interactive probe of eight flag forms. The plz subcommand is the interactive fallback for when none of them worked or when you want the reference material rather than the built-in usage text.

Both are configurable. The custom pager option changes what plz uses to display the man page, and the custom cheat.sh host URL option points the cheat sheet lookup at a different host, which matters for anyone behind a firewall or on a private instance.

The prompt-driven selection is the right choice for a subcommand named plz, which is short for please, and it keeps the interactive path separate from the default path so that piping halp output into another command is not broken by a menu.

Installing with cargo, pacman or Docker

The package is on crates.io, and the minimum supported Rust version is 1.74.1.

cargo install halp

On Arch Linux it is in the extra repository, so pacman handles it.

pacman -S halp

There are AUR packages as well, and the AUR helper route is shown with paru.

paru -S halp-git

Or you clone the AUR package and build it with makepkg, which is the route to take if you want to read the PKGBUILD before running it.

git clone https://aur.archlinux.org/halp-git.git && cd halp-git && makepkg -si

Docker builds are automated and the images are published to Docker Hub and the GitHub Container Registry. The usage pattern passes the command you want to inspect as the container's command.

docker run --rm -it "orhunp/halp:${TAG:-latest}" whoami
docker run --rm -it "orhunp/halp:${TAG:-latest}" plz whoami

Two details in the Dockerfile are worth knowing if you use the image. The runner stage is based on debian:buster-slim, and the build removes the man page path exclusion from the dpkg configuration and installs man-db and manpages with a mandb run, so the man page path in the container actually resolves. It also reinstalls coreutils, which the README's Docker section hints at with a note about shared library errors when you mount your own binary.

The command set and how the binaries are split

The Cargo manifest shows a package with four binaries, which is unusual for a small CLI and explains the size of the install.

The main halp binary is the default run. Then there is halp-completions, which generates shell completions, halp-mangen which generates a man page, and halp-test, a helper binary used by the test suite. The completions and man page generators are the reason the project can install itself into a system with the same care as any other command line tool rather than being a script you alias.

The dependency list is a good indicator of what the tool actually does. clap 4.6.1 with the derive, env and wrap_help features for the argument parsing. clap_complete and clap_mangen for the two generators. colored and console for the coloured status output that shows each flag being tried. dialoguer for the interactive selection in plz. process_control for running the target command and reacting to it. serde and toml for the configuration file. ureq for the HTTP request to cheat.sh. And thiserror for the error types.

The Rust edition is 2021, the release profile uses lto with a single codegen unit and strips symbols, and the panic strategy differs between the dev profile, which aborts, and the release profile, which unwinds.

Configuration and customising the flag list

The README lists a configuration file as one of the two ways to customise the behaviour, alongside providing a list of arguments on the command line. So there are three levels of control.

The defaults cover the eight common forms. A configuration file changes that set persistently, and a command line argument overrides it for one invocation.

The options the README documents in its examples include checking a custom argument, disabling the defaults entirely so that only what you specify is tried, and verbose logging, which is how you see the sequence of attempts rather than just the winning output.

The disable-defaults case is the one that makes this more than a convenience wrapper. A tool with an unusual convention, where -h means something else entirely, is exactly the case where the default probe produces a wrong answer, and switching the defaults off makes halp probe only the flags you trust.

The configuration file format is TOML, given the toml crate in the dependency list, and the config/ directory at the top level of the repository is where the default configuration lives.

Where halp is the wrong tool

The first limitation is that halp is a probe, not a parser. It tries flags and watches the exit code. A tool that prints its help to stdout and then exits with a non-zero status is treated as a failure, and a tool that ignores unknown flags silently and exits 0 will be reported as a success on the first attempt regardless of whether the output was actually help. The README's own framing, checking the exit code, is a good heuristic and an imperfect one.

The second is that it runs the command. Each attempt executes the target program, so on a command with side effects, a command that does something on an unrecognised flag, or a slow command, the probe is not free. The README positions halp for help and version checks, where the risk is low, and it is not a general wrapper for arbitrary commands.

The third is that the flag list is a guess about conventions. The four help forms and the four version forms cover most of the ecosystem, but a tool using --usage or -? or a version subcommand under a different name is not covered, and the configuration file is where you fix that, which means the tool is only as good as your willingness to configure it.

The fourth is the cheatsheet path, which reaches out to cheat.sh over HTTP through ureq. That is a network call to a third-party service triggered by an interactive subcommand, and it is worth knowing that it happens. A reader on an air-gapped machine gets a man page or nothing.

The fifth is the age of the releases. The most recent published release is v0.2.0 from June 2024, with v0.1.7 from June 2023, so the version number has not moved in over two years, even though the last push to the repository was on 2026-10-01. The README's own packaging status badge and the Repology link suggest a project that gets occasional attention rather than a steady release cadence, so a version in a Dockerfile tag is worth pinning deliberately.

Licence, maintenance and the shape of the project

The licence is a choice of MIT or Apache-2.0, expressed in the manifest as MIT OR Apache-2.0, and the repository carries both LICENSE-APACHE and LICENSE-MIT. The author is Orhun Parmaksız. For a tool that gets installed system-wide, a dual permissive licence is the least surprising choice available.

The repository is not archived and the last push was on 2026-10-01, so the code is being touched. The release history is slower than the commit history, and the manifest carries a comment next to the version field saying it is bumped by release.sh, which tells you releases are scripted rather than manual.

The quality tooling is thorough for a project of this size. There is a continuous integration workflow, a continuous deployment workflow, a Docker build workflow, Codecov coverage, a cliff.toml for changelog generation, a deny.toml for cargo-deny, a codespell ignore file, a rustfmt configuration and a committed.toml.

What the project does not have is an editor integration, a shell wrapper or a way to make the result machine readable in a format other than the coloured terminal output. If you want halp's answer in a script rather than in front of your eyes, you would be parsing the output, and the project does not promise a stable machine format to do that against.

Editorial conclusion

halp suits someone who lives in a terminal and hits tools with inconsistent help conventions, since a single halp command covers the four common help forms and the four version forms in one pass. It does not suit a user whose shell already has completion and a man page, because the tool exists to work around exactly that gap. Verify the Rust version first, at 1.74.1, and note that the Docker image is built on Debian buster, which is old enough to matter if you rely on it for a non-root user.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. orhun/halp on GitHub
3. Project website
4. README
5. Releases