Add `[help]` recipe attribute so `just <recipe> --help` runs `just --usage <recipe>`
- Dominant language
- Rust
- Stars
- 35.8k
- Forks
- 846
- Avg merge
- 27m
- Merged PRs (30d)
- 3
Description
## Summary
Add a new recipe attribute, `[help]`, that makes `just --help` print the recipe usage output (same as `just --usage `) and exit, without running the recipe.
## Motivation
`just --usage ` 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 --help`.
## Proposed behavior
Given a recipe marked with `[help]`:
- `just --help` behaves exactly like `just --usage `.
- The recipe body is not executed.
- Exit code is 0.
If a recipe is not marked with `[help]`, behavior is unchanged.
## Example
```just
[help]
[arg("FLAG", long="flag", value="--flag", help="Enable the optional behavior")]
[arg("MODE", long="mode", value="--mode ", help="Select a mode (example: fast, safe)")]
[arg("TARGET", long="target", value="--target ", 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.
Contributor guide
Assessment
This issue has not been assessed yet.