Value flag can't take a value starting with - when it collides with a short flag (need allow_hyphen_values)

[sassdavid]

I'm using usage to wrap another CLI (terragrunt/terraform) where one flag carries a passthrough string handed verbatim to the inner tool. That flag can't reliably receive a value that begins with -: whether it works depends on whether the value's first letter happens to match one of my own short flags.

Minimal repro, no mise, just usage:

cat > repro <<'EOF'
#!/usr/bin/env -S usage bash
#USAGE flag "-d --working-dir <DIR>"
#USAGE flag "-a --args <ARGS>"
echo "working_dir=[${usage_working_dir:-}] args=[${usage_args:-}]"
EOF
chmod +x repro

./repro -a -destroy   # working_dir=[estroy] args=[]     <- -destroy read as -d + estroy
./repro -a -foo       # working_dir=[]        args=[-foo] <- fine, no -f defined
./repro -a -dfoo      # working_dir=[foo]     args=[]     <- clustered as -d + foo

So -a -destroy silently loses the value: -destroy is tokenized as the cluster -d estroy and the leftover lands in --working-dir, while -a ends up empty and nothing errors. -a -foo happens to work only because no -f flag exists — add one and the same passthrough breaks. That first-letter dependence is the surprising part for a flag whose whole job is to forward arbitrary args.

Neither = form helps: --args=-destroy hits the same hijack, and -a=-destroy keeps the literal = in the value.

The only thing that works today is padding the value with a leading space so it's no longer seen as a flag:

./repro -a ' -destroy'   # working_dir=[] args=[ -destroy]

Workable, but easy to forget, and the failure mode (a garbage value on an unrelated flag) is hard to diagnose.

Ask: a way to opt a flag/arg into accepting hyphen-leading values, like clap's allow_hyphen_values:

#USAGE flag "-a --args <ARGS>" allow_hyphen_values=#true

Separate from the feature: when the value collides with a short flag it's silently reassigned to that flag instead of erroring, so a required-value flag can come out empty with no diagnostic.

Version: usage-cli 3.5.4, macOS arm64.

[jdx]

Implemented this in #715.

The PR adds allow_hyphen_values=#true for value-taking flags, so a spec like:

flag "-a --args <ARGS>" allow_hyphen_values=#true

now lets -a -destroy bind -destroy as the value for args before the parser tries to split it as a short-flag cluster. I also added regression coverage for the short-flag collision, --args=-destroy, and the unchanged default behavior when the option is not set.

This comment was generated by Claude Code.