eza --hyperlink eats the next positional argument

My ls is a shell function wrapping eza with a bare --hyperlink flag. After upgrading to eza v0.23.5, ls Desktop started failing:

error: invalid value 'Desktop' for '--hyperlink [<WHEN>]'
  [possible values: always, auto, never]

v0.23.5 (2026-07-09) switched eza to clap for argument parsing and added --hyperlink=auto. --hyperlink is now an optional-value option ([<WHEN>]). With clap, a bare --hyperlink greedily consumes the next token as its value, so eza --hyperlink Desktop parses Desktop as the value and rejects it.

Usage

Attach the value with = so clap doesn’t reach for the next positional:

# ~/.commonrc
if _have eza; then
  ls() {
    if [[ -t 1 ]]; then command eza --hyperlink=auto "$@"
    else command eza "$@"; fi
  }
  alias lt='eza --tree --level=2 --long --icons --git --hyperlink=auto'
fi

The bare form is the broken one; the attached form works:

$ eza --hyperlink /etc/hosts
error: invalid value '/etc/hosts' for '--hyperlink [<WHEN>]'
  [possible values: always, auto, never]

$ eza --hyperlink=auto /etc/hosts
/etc/hosts

That wrapper is part of a tty-aware pattern I use for eza, ripgrep, and fd: separate writeup.

Notes

• The = matters more than the value here. auto matches the bare flag’s prior default (emit OSC 8 links only on a real terminal). always would force links even when eza doesn’t detect terminal support.
• The root cause is clap’s handling of optional arguments that don’t require values: without require_equals, the parser pulls the following token into the option.

References

• eza CHANGELOG.md: v0.23.5 “Use Clap instead of manual cli args parsing” and “Implement --hyperlink=auto”.
• eza(1) --hyperlink=WHEN: always / auto / never semantics.
• clap discussion #3897: Optional arguments that don’t require values: why the bare flag swallows the next token.