casey / casey/just

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

Open
#3,064 4 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.