Add `[help]` recipe attribute so `just <recipe> --help` runs `just --usage <recipe>`

[pygarap]

Summary

Add a new recipe attribute, [help], that makes just <recipe> --help print the recipe usage output (same as just --usage <recipe>) and exit, without running the recipe.

Motivation

just --usage <recipe> already generates a useful usage block, including parameter help added via [arg(..., help="...")]. For recipes that are meant to be invoked like small CLIs, it is more natural to support the common pattern just <recipe> --help.

Proposed behavior

Given a recipe marked with [help]:

• just <recipe> --help behaves exactly like just --usage <recipe>.
• The recipe body is not executed.
• Exit code is 0.

If a recipe is not marked with [help], behavior is unchanged.

Example

[help]
[arg("FLAG", long="flag", value="--flag", help="Enable the optional behavior")]
[arg("MODE", long="mode", value="--mode <mode>", help="Select a mode (example: fast, safe)")]
[arg("TARGET", long="target", value="--target <path>", help="Path to operate on")]
do-thing FLAG="" MODE="" TARGET="":
  echo "running with {{FLAG}} {{MODE}} {{TARGET}}"

Expected:

• just do-thing --help prints the same output as just --usage do-thing, including the help="..." strings from the [arg(...)] annotations.
• just do-thing --mode fast --target ./src --flag runs the recipe normally.

Compatibility notes

This is opt-in per recipe. Marking a recipe with [help] reserves the literal --help token for usage output for that recipe, rather than treating it as a normal argument value.

[casey]

I see the utility, but I'm not totally convinced, just because it's so close to just --usage recipe. One thing that I would prefer to do as a first step would be make --help take an argument, and then print out the usage string of that recipe if it's passed an argument. That would make just -h recipe work, which seems pretty convenient, and maybe gets you 80% of the benefit without having to add a new attribute, which then has to get added to every recipe where you want to use it.

[drewhoener]

I see the utility, but I'm not totally convinced, just because it's so close to just --usage recipe. One thing that I would prefer to do as a first step would be make --help take an argument, and then print out the usage string of that recipe if it's passed an argument. That would make just -h recipe work, which seems pretty convenient, and maybe gets you 80% of the benefit without having to add a new attribute, which then has to get added to every recipe where you want to use it.

For me it's more about what devs are used to. I expect generally within a command system that command <sub_command> --help/-h will show the usage menu for that command, I'd support this feature

[djpeach]

Also expected this to just be how it worked. Most cli tools have something like mycli --help (all commands docs) or mycli subcommand --help (just subcommand docs).

Happy to see just --usage cmd I did not see that in the README (I searched for --help)