casey / casey/just

Complete recipe parameters and `arg` flags in Zsh

Open
#3,523 12 comments 2 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
35.8k
Forks
846
Avg merge
27m
Merged PRs (30d)
3

Description

## Summary

Please extend the existing Zsh completion support so it can complete recipe-specific parameters, options, and flags from the resolved `justfile`.

`just` 1.55.1 already provides Zsh completion scripts via `just --completions zsh`, and the generated Zsh script delegates to `JUST_COMPLETE=zsh just`. This request is to make that existing completion path more recipe-aware after a recipe has been selected.

## Current behavior

Zsh completion can be installed with:

```console
$ mkdir -p ~/.zsh/completions
$ just --completions zsh > ~/.zsh/completions/_just
```

And then enabled in `.zshrc` with:

```zsh
fpath=(~/.zsh/completions $fpath)
autoload -U compinit
compinit
```

This provides completion for `just` itself and available recipes, but it does not complete the selected recipe's own parameters, options, and flags declared with `[arg(...)]`.

## Example

```just
[arg("target", help="Test target")]
[arg("verbose", long="verbose", value="--verbose", help="Use verbose output")]
test target verbose="":
cargo test {{verbose}} {{target}}
```

Expected completion behavior:

```console
$ just
test

$ just test --
--verbose Use verbose output
```

## Requested behavior

- Complete recipes from the resolved `justfile`, using the same justfile discovery behavior as a normal `just` invocation.
- After a recipe is selected, complete only the parameters, options, and flags that belong to that recipe.
- Complete long options and flags declared with `[arg(ARG, long="LONG")]`.
- Complete short options and flags declared with `[arg(ARG, short="S")]`.
- Include help text from `[arg(ARG, help="HELP")]` in Zsh completion descriptions when available.
- Support flags declared with `[arg(ARG, long="LONG", value=VALUE)]` or `[arg(ARG, short="S", value=VALUE)]`.
- Support options that take values, including repeatable variadic options.
- Avoid suggesting unrelated recipe names where recipe-specific arguments, options, or flags are expected.

## Motivation

This would make Zsh completion more useful for `justfile`s that expose recipes as small command-line interfaces with documented parameters, options, and flags.

Contributor guide

Open the contributing guide

Research direction

Start by tracing the `just --completions zsh` generated script and its `JUST_COMPLETE=zsh just` completion path, then inspect how the resolved `justfile` and selected recipe are handled. Exercise the example `[arg(...)]` declarations and verify that recipe-specific long and short options, values, repeatable variadic options, and help descriptions appear only after the recipe is selected.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, zsh
Domain
cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.