[opensourcedex]

halp is a free, open source frameworks & platforms project written in Rust and released under Apache-2.0. It has 768 GitHub stars, 14 forks and 6 open issues, and was last pushed 30 days ago. On this registry it ranks #80 of 84 tracked projects in Frameworks & Platforms, with 5 head-to-head comparisons available.

What is halp?

halp is a command-line utility written in Rust, licensed under Apache-2.0, that finds the working help and version arguments for other command-line tools and offers a prompt for their manual page or cheat sheet — built for developers and system administrators who live in a terminal and cannot remember whether a given tool answers to -h, -H, --help or help.

What it is

halp belongs to the ecosystem of terminal and shell tooling: a single small binary you invoke in front of another command. Its homepage is hosted at halp.cli.rs, the source is Rust, and the project carries the topics cli, cli-helper, cli-tools, command-line-tool, help and helper. Rather than being a help system of its own, it is an adapter that sits between you and the hundreds of unrelated command-line programs already installed on your machine, each of which has its own opinion about how to be asked for information.

The concrete problem it solves is argument-convention drift. Many tools reject -h because that letter is already taken by another flag, others use -V instead of -v, and some accept a bare help word. The result is the manual brute-force cycle the README reproduces: try -v, get an unknown-flag error; try -V, get another; try -h, get a third; eventually land on --help. halp performs that search for you against a predefined list of commonly used options and flags, stopping at the first argument that succeeds with exit code 0 and printing that output, so version and help can be retrieved in one command. It replaces the guessing loop itself.

Key capabilities

  • Probes a fixed candidate list for help output: --help, -h, help and -H, in order.
  • Probes a matching list for version information: --version, -v, version and -V.
  • Prints the successful argument's output and exits as soon as one candidate returns exit code 0, distinguishing success and failure per attempt in its output.
  • Provides a plz subcommand that prompts for either the manual page, which it shows by running man(1), or the cheat sheet, which it fetches via cheat.sh.
  • Allows the candidate argument list to be replaced or extended through a configuration file or supplied directly as command-line arguments, including disabling the defaults entirely.
  • Supports verbose logging, so each attempted argument can be traced.
  • Supports a custom pager and a custom cheat.sh host URL.

Who uses it and how

  • Developers working in shells where completions are unavailable or incomplete, who need to interrogate unfamiliar tools without leaving the prompt.
  • Arch Linux users, who install it from the extra repository with pacman -S halp or from AUR packages such as halp-git built with an AUR helper or makepkg.
  • Rust developers, who install it from crates.io with cargo install halp; the minimum supported Rust version is 1.74.1.
  • Container and automated environments, where prebuilt Docker images published through the project's automated Docker builds can be used instead of a local installation.
  • Users on networks where the public cheat.sh service is unreachable or undesirable, who redirect the cheat sheet lookup to a different host URL.

Getting started

Install from crates.io with cargo install halp, from the Arch Linux extra repository with pacman -S halp, or use the published Docker images; binary releases and build-from-source instructions are documented as alternatives in the README.

How it compares

The facts name no paid products that halp replaces. Among the tools it names, halp does not compete with man(1) or cheat.sh — it dispatches to them, running man(1) for the manual page and querying a cheat.sh host for the cheat sheet. Its own contribution is the prior step: resolving which argument a given tool actually accepts, which neither man(1) nor cheat.sh attempts to discover for you.

When to use it — and when not to

Operationally it is cheap: a single binary with no database, object storage, mail service or background daemon to run, which makes it easy to drop onto a workstation or into an image. Its main limitation is that it only tries a predefined list, so a tool with wholly unconventional help switches will still be reported as failing every candidate unless the list is extended by configuration — and the cheat-sheet path depends on reaching cheat.sh unless a custom host is configured. Anyone who needs a full manual-page renderer, a completion generator, or a project with a large contributor base should look elsewhere; with 768 stars and 14 forks, halp is a small, single-purpose utility.

project readme (upstream, from github) — read inline

A CLI tool to get help with CLI tools 🐙

GitHub Release Crate Release Coverage
Continuous Integration Continuous Deployment Docker Builds Documentation

halp aims to help find the correct arguments for command-line tools by checking the predefined list of commonly used options/flags. Additionally, it provides a prompt for quick access to the manual page or cheat sheet of the given command.

If you deal with command-line tools often, it might take some time to figure out how to get help or check the version of a particular command (especially when shell completions are not available). In that case, you might try the most-known flags such as -h and -v but unfortunately not all the command-line tools follow these conventions (either due to conflicts with other flags or they just use another form). Instead of brute-forcing manually into getting help, you can run halp and it will check the following arguments for you:

  • for help: --help, -h, help, -H
  • for version info: --version, -v, version, -V

If one of these arguments succeeds (with exit code 0), it prints the output and exits. This way, you can get informed about the version and help in one single command. You can also customize this list with a configuration file or provide a list of arguments via command-line arguments.

On the other hand, if you really need help, you can use the plz subcommand which will prompt a selection for:

  1. show the man page (runs man(1))
  2. show the cheat sheet (via cheat.sh)
Table of Contents

Example

Have you ever experienced this:

$ cli_tool -v
unknown flag -v

$ cli_tool -V
unknown flag -V

$ cli_tool -h
unknown flag -h

$ asdjw1jwhdajh1idojad # frustration
bash: asdjw1jwhdajh1idojad: command not found

$ cli_tool --help # f*cking finally!
Some CLI Tool Version 1.42.69
Usage:
  cli_tool <flags> <args> [--parameter1 value1 --parameter2 value2 ...]

Whereas with halp:

$ halp cli_tool

(°ロ°)  checking 'cli_tool -v'
(×﹏×)      fail '-v' argument not found.
(°ロ°)  checking 'cli_tool -V'
(×﹏×)      fail '-V' argument not found.
(°ロ°)  checking 'cli_tool -h'
(×﹏×)      fail '-h' argument not found.
(°ロ°)  checking 'cli_tool --help'
\(^ヮ^)/ success '--help' argument found!

Some CLI Tool Version 1.42.69
Usage:
  cli_tool <flags> <args> [--parameter1 value1 --parameter2 value2 ...]

Installation

Packaging status

Packaging status

Cargo

halp can be installed from crates.io:

cargo install halp

The minimum supported Rust version is 1.74.1.

Arch Linux

halp can be installed from the extra repository using pacman:

pacman -S halp

Or you can install the available AUR packages using an AUR helper. For example,

paru -S halp-git

Alternatively, you can clone the AUR package and then build it with makepkg. For example,

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

Docker

Images

Docker builds are automated and images are available in the following registries:

Usage

The following commands can be used to get help for a binary inside the container:

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

Or you can provide a custom binary as follows (please note that you might get shared library errors):

docker run -v "bin:/app/bin:rw" --rm -it "orhunp/halp:${TAG:-latest}" -v ./bin
Building

Custom Docker images can be built from the Dockerfile:

docker build -t halp .

Binary releases

See the available binaries for different targets from the releases page. They are automated via Continuous Deployment workflow

Release tarballs are signed with the following PGP key: 0xFB41AE0358378256

Build from source

  1. Clone the repository.
git clone https://github.com/orhun/halp && cd halp/
  1. Build.
CARGO_TARGET_DIR=target cargo build --release

Binary will be located at target/release/halp.

Usage

halp [OPTIONS] <CMD>

Options:
      --check <ARG>    Sets the argument to check
      --no-version     Disable checking the version information
      --no-help        Disable checking the help information
  -c, --config <PATH>  Sets the configuration file [env: HALP_CONFIG=]
  -t, --timeout <S>    Sets the timeout for the command [default: 5]
  -v, --verbose        Enables verbose logging
  -h, --help           Print help
  -V, --version        Print version

plz

halp [OPTIONS] plz <CMD>

Options:
  -m, --man-cmd <MAN_CMD>   Sets the manual page command to run
      --cheat-sh-url <URL>  Use a custom URL for cheat.sh [env: CHEAT_SH_URL=]
  -p, --pager <PAGER>       Sets the pager to use
      --no-pager            Disables the pager
      --insecure            Disables TLS certificate verification for HTTP requests
  -h, --help                Print help

Examples

Check help and version (default)
halp whoami

halp example I

Check a custom argument
halp --check "\--silent" zps

(You can escape - with using \-.)

You can also provide multiple arguments as follows:

halp --check "help" --check "test" menyoki
Disable defaults
halp --no-version sha512sum

halp --no-help sha512sum
Verbose logging
halp --verbose git-cliff

This will result in stderr/stdout being printed if there was an error. For example:

(°ロ°)  checking 'git-cliff -v'
(×﹏×)      fail '-v' argument not found.
(o_O)      debug
stdout:
 WARN  git_cliff > "cliff.toml" is not found, using the default configuration.
 ERROR git_cliff > Git error: `could not find repository from '.'; class=Repository (6); code=NotFound (-3)`
Get additional help (via plz)
halp plz vim

halp example II

Custom pager
halp plz --pager bat vim

To disable the pager:

halp plz --no-pager bat vim
Custom cheat.sh host URL
halp plz --cheat-sh-url https://cht.sh vim
Skipping TLS certificate verification

Behind a TLS-inspecting proxy the providers are reached through a certificate that is not in the system trust store, which fails with invalid peer certificate: UnknownIssuer. To skip verification:

halp plz --insecure vim

This disables certificate checking for the request, so only use it on networks you trust.

Configuration

halp can be configured with a configuration file that uses the TOML format. It can be specified via --config or HALP_CONFIG environment variable. It can also be placed in one of the following global locations:

  • `` / halp.toml
  • `` / halp/halp.toml
  • `` / halp/config

`` depends on the platform as shown in the following table:

Platform Value Example
Linux $XDG_CONFIG_HOME or $HOME/.config /home/orhun/.config
macOS $HOME/Library/Application Support /Users/Orhun/Library/Application Support
Windows {FOLDERID_RoamingAppData} C:\Users\Orhun\AppData\Roaming

See halp.toml for the default configuration values.

Funding

If you find halp and/or other projects on my GitHub profile useful, consider supporting me on GitHub Sponsors or becoming a patron!

Support me on GitHub Sponsors Support me on Patreon Support me on Patreon

Contributing

See our Contribution Guide and please follow the Code of Conduct in all your interactions with the project.

License

Licensed under either of Apache License Version 2.0 or The MIT License at your option.

🦀 ノ( º _ º ノ) - respect crables!

Copyright

Copyright © 2023-2024, Orhun Parmaksız

Frequently asked questions

Is halp free to use?

halp is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does halp do?

A CLI tool to get help with CLI tools 🐙

What is halp written in?

halp is primarily written in Rust. Its source is publicly available at https://github.com/orhun/halp, and it has 768 GitHub stars.