halp

halp turns a natural-language task into a shell command grounded in the selected tool's help or man page. It talks to an OpenAI-compatible LLM endpoint and does not execute suggestions unless -a is enabled and the user confirms.

Install

Install the published package with:

python -m pip install halp-cli

To install the current checkout instead:

python -m pip install .

For local development, use python -m pip install -e .. The install provides the halp command.

Usage

halp [OPTIONS] <tool> "<prompt>"

Example for a local Gemma server:

halp -l gemma4:e4b -ip 127.0.0.1:8001 nmap "Scan the top 10 TCP ports on 8.8.8.8"

By default, halp prints the suggested command and exits. It checks that the requested tool is installed, gathers -h and --help output, then tries no-argument usage and a man page. Help collection is time-limited and capped; the captured context is trimmed to fit -c with room reserved for the prompt and model response.

Options

Extra parameter examples:

halp -extra-args 'temperature=0.2,top_p=0.9' nmap "Scan localhost"
halp -extra-args '{"temperature":0.2,"top_p":0.9}' nmap "Scan localhost"

halp manages the model, messages, prompt, max_tokens, and stream fields, so extra arguments cannot override them. The default endpoint probe tries standard /v1/chat/completions first, then common chat and completions route variants.

Interactive workbench

Start with -p. Enter a refinement directly or use an action:

• /refine TEXT — refine the current command
• /task TEXT — start a new task
• /retry — request another suggestion for the same task
• /history and /use N — review suggestions and select a prior candidate
• /copy — copy the current command using wl-copy, xclip, xsel, or pbcopy when available
• /run — run the current candidate (available only with -a, always asks for confirmation)
• /clear, /help, /quit

When -a is active, halp asks whether to execute every newly generated command. In the workbench, /run can also execute the current candidate after another confirmation. Output from accepted commands streams directly to the terminal.