Skip to content

fix(cli): show help for bare exec command - #1361

Merged
jdx merged 1 commit into
mainfrom
fix/exec-bare-help
Sep 1, 2026
Merged

fix(cli): show help for bare exec command#1361
jdx merged 1 commit into
mainfrom
fix/exec-bare-help

Conversation

@jdx

@jdx jdx commented Sep 1, 2026

Copy link
Copy Markdown
Owner

Fixes #1360.

exec intentionally owns -h and --help so a fully specified invocation can render the wrapped script's usage spec. Handle the bare command before required positional validation so usage exec --help prints the exec command page instead of reporting a missing <COMMAND>.

This preserves wrapped-script help for usage exec <COMMAND> <BIN> --help and supports the x alias plus both help spellings.

Tests:

  • cargo test -p usage-cli --all-features
  • cargo clippy -p usage-cli --all-features --all-targets -- -D warnings

This PR was generated by Codex.


Note

Low Risk
Small pre-parse branch in the CLI entrypoint; behavior change is limited to bare exec help and is covered by new tests.

Overview
usage exec -h / usage exec --help (and the x alias) now print the exec subcommand help instead of failing on missing <COMMAND> / <BIN>.

Cli::run intercepts that two-argument pattern before normal parsing and renders the exec page via usage_rs::help::render_styled, matching what usage help exec already shows. Invocations with a command and binary still route -h/--help to the wrapped script’s usage, unchanged.

Integration test test_exec_help_without_a_script covers exec/x × -h/--help and expects success with empty stderr.

Reviewed by Cursor Bugbot for commit be4fdc1. Bugbot is set up for automated code reviews on this repo. Configure here.

@jdx
jdx merged commit 1525439 into main Sep 1, 2026
10 checks passed
@jdx
jdx deleted the fix/exec-bare-help branch September 1, 2026 18:51
jdx added a commit that referenced this pull request Sep 2, 2026
Rebasing brought in #1361, which answers `usage exec -h` with the command's
own page instead of an error about the missing positionals. Two things follow:

- The help said `-h` and `--help` print the script's page "rather than this
  one", which is now only true once a script is named. It says both halves.
- The test that shipped with #1361 asserts the command's first help line, and
  this branch rewrote it. It now matches on a fragment rather than the whole
  sentence, because the renderer wraps the page to the terminal width and the
  full line arrives with a newline in it.

Generated artifacts are regenerated against the rebased tree, which also picks
up the 6.6.1 version bump.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Instruction counts

benchmark trend instructions Δ wall (min) Δ
markdown █▁ 341,374,535 → 341,326,870 -0.01% 57.26 → 57.18ms -0.14%
startup ▁█ 903,091 → 903,841 +0.08% 1.15 → 1.16ms +0.44%

No instruction-count regression above 1%.

Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.

Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework stripped binary, bytes
usage 1344728
bpaf 2493216
clap 3101656
framework instructions, cold parse vs usage
usage 8218
clap 6313214 768x
bpaf 21909171 2665x
                                              min       p01       p10    median
usage-rs: argv -> struct                     1141      1170      1179      1221  ns
clap: build tree + parse -> struct        1792822   1796017   1801295   1810452  ns
bpaf: build parser + parse -> struct      5623120   5623120   5644864   5676868  ns

usage: argv -> struct                            1212 ns      1.21 µs
clap: build tree + parse -> struct            1816139 ns   1816.14 µs
clap: parse -> struct, tree reused              72143 ns     72.14 µs
clap: build tree only                         1050259 ns   1050.26 µs

be4fdc1ee4f1 vs 1dd4feb5df0a · measured on the runner, not pushed to the history.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

usage exec --help errors

1 participant