jdx/usage v6.0.0 on GitHub

6.0.0 - 2026-08-22

🚀 Features

(argv) add a zero-allocation argv parser by @jdx in #798
(argv) emit a usage spec from static metadata by @jdx in #801
(argv) a bound stops a variadic by @jdx in #826
(argv) route a word that names nothing to the default subcommand by @jdx in #848
(argv) join static tables at compile time by @jdx in #851
(argv) render the usage line, byte-identical to usage-lib's by @jdx in #854
(argv) render -h, byte-identical to usage-lib's by @jdx in #860
(argv) render --help too, byte-identical to usage-lib's by @jdx in #866
(argv) answer --help and -h by @jdx in #870
(argv) answer the help subcommand by @jdx in #872
(argv) split a command line the way the shell that typed it would by @jdx in #874
(argv) read the cursor's position off a real parse by @jdx in #876
(argv) offer what the reference offers, from compiled tables by @jdx in #877
(argv) generate the shell script each shell wants by @jdx in #887
(argv) let a Rust function answer for a value by @jdx in #888
(argv) write the run= a declared completer answers by @jdx in #890
(argv) say what went wrong the way clap says it by @jdx in #895
(argv) suggest what was probably meant by @jdx in #897
(argv) answer --version, which an adopter loses on the way from clap by @jdx in #909
(argv) a flag whose value may be left off by @jdx in #969
(argv) take flag-like detached values when declared by @jdx in #1012
(bench) count what a parse allocates, and stop allocating for commands nobody ran by @jdx in #829
(cli) hold a spec's declaration order, the way clap-sort holds a clap CLI's by @jdx in #915
(cli) parse usage's own command line with the parser usage ships by @jdx in #965
(cli) support long version text by @jdx in #1120
(cli) check that examples still parse, and let the derive declare them by @jdx in #1168
(cli) add usage explain by @jdx in #1179
(cli) add usage diff for spec compatibility checking by @jdx in #1171
(complete) complete config keys and values from the spec by @jdx in #840
(complete) add async runtime overlays by @jdx in #1060
(complete) support command value hints by @jdx in #1081
(complete) add shell quoting filter by @jdx in #1114
(complete) support full value hint vocabulary by @jdx in #1119
(complete) expand partial path segments by @jdx in #1128
(complete) support shell alias registration by @jdx in #1158
(complete) breaking remove the vendored bash-completion copy by @jdx in #1176
(complete) install a completion script where its shell looks for it by @jdx in #1188
(config) read config files as a layer by @jdx in #856
(config) explain why a setting has the value it has by @jdx in #857
(config) read a resolution as the types a struct holds by @jdx in #862
(config) generate the settings registry from the spec by @jdx in #864
(config) generate the settings struct a CLI reads by @jdx in #865
(config) hold a value to the choices its setting declares by @jdx in #868
(config) carry a setting's choices into the generated registry by @jdx in #869
(config) say what sort of thing each warning is by @jdx in #873
(config) carry the flags a setting declares into its registry by @jdx in #880
(config) read the command line as a layer by @jdx in #881
(config) compare the flags a spec declares with the flags a CLI binds by @jdx in #884
(config) support optional props and aliases by @jdx in #1134
(config) read YAML config files by @jdx in #1192
(config) ask for provenance by key, like a value by @jdx in #1195
(config) a read that keeps every setting that reads by @jdx in #1196
(config) close Config derive and spec authoring gaps by @jdx in #1202
(config) gate deprecated settings by explicit CLI version by @jdx in #1201
(derive) compile a struct into parse tables and a spec by @jdx in #803
(derive) compile subcommands from an enum by @jdx in #816
(derive) check what a parse cannot decide on its own by @jdx in #817
(derive) nest commands to any depth by @jdx in #818
(derive) declare which flags conflict and which require each other by @jdx in #820
(derive) let a flag displace another, the last one given winning by @jdx in #821
(derive) let a command answer to more than one name by @jdx in #827
(derive) let a variant hold its command in a Box by @jdx in #828
(derive) let a field be the type it means by @jdx in #833
(derive) declare the words a value may be by @jdx in #838
(derive) hold the bytes a word arrived as by @jdx in #841
(derive) declare the properties mise patches in by hand by @jdx in #842
(derive) accept a value the OS accepts and UTF-8 does not by @jdx in #844
(derive) share declarations between commands with flatten by @jdx in #852
(derive) say three things about a CLI the spec could and the derive could not by @jdx in #853
(derive) answer a completion request from the binary itself by @jdx in #885
(derive) bind a flag to a setting, from what the parser saw by @jdx in #889
(derive) a setting can be declared wherever a flag is by @jdx in #896
(derive) let a field name the function that completes it by @jdx in #892
(derive) say how an argument relates to --, all four ways by @jdx in #900
(derive) a default a collecting field can hold by @jdx in #902
(derive) say what a command does to the world by @jdx in #905
(derive) name a value the way clap names it, and say which usage can read the spec by @jdx in #907
(derive) let parse() answer a failure the way a program does by @jdx in #910
(derive) read the package's version, and be called what the binary is called by @jdx in #917
(derive) a command that takes nothing can be written that way by @jdx in #923
(derive) say that a command cannot be run alone, which it knew and did not write by @jdx in #937
(derive) keep command aliases on their args by @jdx in #946
(derive) preserve verbatim doc comments by @jdx in #949
(derive) support path value hints by @jdx in #951
(derive) declare a group where the flags are declared by @jdx in #934
(derive) add value-conditional requirements by @jdx in #1002
(derive) add skip for fields that are not arguments by @jdx in #1009
(derive) support inline subcommand fields by @jdx in #1055
(derive) accept runtime metadata expressions by @jdx in #1056
(derive) accept clap value attributes by @jdx in #1057
(derive) parse full argv with program name by @jdx in #1063
(derive) support clap no binary name by @jdx in #1064
(derive) support unit command structs by @jdx in #1071
(derive) reuse args across commands by @jdx in #1076
(derive) support runtime program identity by @jdx in #1078
(derive) preserve value enum metadata by @jdx in #1079
(derive) accept clap field spellings by @jdx in #1086
(derive) preserve hidden flag aliases by @jdx in #1087
(derive) resolve relationships through flatten by @jdx in #1088
(derive) support flattened overrides by @jdx in #1089
(derive) preserve flattened help headings by @jdx in #1090
(derive) support clap casing policies by @jdx in #1094
(derive) bind value enums directly by @jdx in #1110
(derive) accept portable clap field spellings by @jdx in #1135
(derive) inherit clap command metadata by @jdx in #1136
(derive) support clap implicit groups by @jdx in #1137
(derive) generate command dispatch by @jdx in #1182
(derive) add usage::Config derive for settings declared in code by @jdx in #1180
(derive) close remaining PLAN gaps for 6.x by @jdx in #1197
(docs) support granular help visibility by @jdx in #1107
(docs) customize subcommand presentation by @jdx in #1108
(docs) color process-facing help by @jdx in #1111
(docs) support help width controls by @jdx in #1113
(docs) support next-line help layout by @jdx in #1117
(docs) support flattened subcommand help by @jdx in #1118
(docs) support explicit display order by @jdx in #1121
(docs) group subcommands under help headings by @jdx in #1153
(docs) add recursive help by @jdx in #1132
(generate) add json-schema for a CLI's config file by @jdx in #839
(go) emit Go parse tables from a spec, which is what Go has instead of a derive by @jdx in #931
(go) emit the cold table too, so generated code can apply the rules by @jdx in #959
(go) render the usage line, from a third table that costs nothing unused by @jdx in #964
(go) render a failure as something a person can act on by @jdx in #977
(go) generate a struct per command, and the Parse that fills them by @jdx in #990
(go) answer the completion request a shell sends by @jdx in #1005
(go) enforce value-conditional requirements by @jdx in #1003
(help) line the flag column up, and give the short page a column at all by @jdx in #912
(help) list the flags a command inherits by @jdx in #913
(help) list --help and --version, which every page answers by @jdx in #914
(lib) add usage-rs facade by @jdx in #963
(lib) ship usage-rs as the one-crate rust default by @jdx in #1041
(parse) support inferred prefixes by @jdx in #1080
(parse) support arg required else help by @jdx in #1093
(parse) add narrow token boundary controls by @jdx in #1097
(parse) preserve trailing delimiters by @jdx in #1098
(parse) add scalar repeat policy by @jdx in #1102
(parse) add subcommand requirement policy by @jdx in #1103
(parse) add argument subcommand conflicts by @jdx in #1104
(parse) add subcommand value precedence by @jdx in #1105
(parse) support missing optional positionals by @jdx in #1106
(parse) support optional flag values by @jdx in #1109
(parse) support custom help and version actions by @jdx in #1123
(parse) accept explicit boolean values by @jdx in #1124
(parse) support non-strict choices by @jdx in #1127
(parse) support ordered environment fallbacks by @jdx in #1130
(parse) warn at runtime when a deprecated declaration is used by @jdx in #1186
(spec) support flag relationships by @jdx in #793
(spec) add help_heading, and render it by @jdx in #802
(spec) allow a mount at the top level by @jdx in #806
(spec) make unknown flags configurable, and keep them as values by @jdx in #810
(spec) add conflicts to flags by @jdx in #819
(spec) say that one flag needs another, which nothing here could by @jdx in #925
(spec) breaking a group, for the rule that no single flag can state by @jdx in #927
(spec) a flag that has to be given on its own by @jdx in #941
(spec) split a value the way clap splits one by @jdx in #961
(spec) add value-conditional requirements by @jdx in #1001
(spec) refuse a detached value when require_equals is set by @jdx in #1013
(spec) bind a value when a flag is given with none by @jdx in #1015
(spec) forward unmatched words as an external subcommand by @jdx in #1021
(spec) bind a default when another flag is given by @jdx in #1023
(spec) add portable expression validation by @jdx in #1037
(spec) add borrowed metadata overlays by @jdx in #1059
(spec) omit versions from metadata views by @jdx in #1066
(spec) support positional conflicts and groups by @jdx in #1085
(spec) add fixed arity value names by @jdx in #1099
(spec) complete relationship families by @jdx in #1100
(spec) expose package metadata by @jdx in #1116
(spec) add deprecation milestones by @jdx in #1129
(spec) add executable views by @jdx in #1143
(spec) add deprecated config environment aliases by @jdx in #1159
(spec) declare source_code_link_template on the derive by @jdx in #1184
(spec) answer usage_spec from a binary's own tables by @jdx in #1183
(spec) reusable flag declarations with flagset and use by @jdx in #1170
(spec) breaking lower the derive's flatten into a flagset by @jdx in #1172
(test) a test harness for an adopter's own suite by @jdx in #1181

🐛 Bug Fixes

(argv) stop a repeatable flag from eating a positional by @jdx in #799
(argv) inherit unknown_flags, which reached one command out of a tree by @jdx in #939
(argv) reject duplicate flags by @jdx in #945
(argv) show choices when a subcommand is required by @jdx in #947
(argv) a bare - binds where it was typed by @jdx in #986
(argv) put zsh's magic comment first, and print fish's candidates as data by @jdx in #1033
(ci) unblock releases by cutting usage-derive's dev-dependency by @jdx in #811
(ci) check the version the crates promise, and promise one that is true by @jdx in #918
(clap) say what clap would do with an unknown flag by @jdx in #899
(cli) recognize about as root command help by @jdx in #794
(complete) resolve config keys through aliases and renames by @jdx in #1169
(config) accept case-insensitive boolean words by @jdx in #1207
(derive) let a ---only argument follow a variadic by @jdx in #823
(derive) three more descriptions a spec keeps and the derive lost by @jdx in #861
(derive) name the mistake when settings has nothing to collect by @jdx in #904
(derive) emit the tables beside the user's types, not in a module above them by @jdx in #938
(derive) a global flag may be given once per command, not once per line by @jdx in #991
(derive) separate value metadata from parsing by @jdx in #1054
(derive) make defaulted fields optional in metadata by @jdx in #1065
(derive) isolate process exit from adopters by @jdx in #1139
(derive) propagate redeclared global values by @jdx in #1140
(derive) preserve set-false actions by @jdx in #1156
(derive) name the count type in standing presence checks by @jdx in #1205
(docs) link multi-word commands to their real source files by @jdx in #845
(docs) link every command to the file that implements it by @jdx in #846
(docs) keep hidden entries out of help by @jdx in #859
(docs) list visible flag aliases by @jdx in #1112
(help) a command's page should say what that command does by @jdx in #911
(help) a declared name is not a short form, and blank help is no help by @jdx in #916
(help) render the page for the mount the words reached by @jdx in #928
(help) a description ending in a break adds no blank line by @jdx in #970
(lib) validate every variadic fallback by @jdx in #1049
(parse) keep every -- after the first by @jdx in #809
(parse) stop losing a flag that is missing its value by @jdx in #807
(parse) answer the five vectors the reference implementation was failing by @jdx in #930
(parse) breaking a command that needs a subcommand says so by @jdx in #992
(parse) keep optional validation lint-clean by @jdx in #1141
(parse) honor separator after automatic args by @jdx in #1164
(parse) let a bundle contain a supplied short by @jdx in #1175
(spec) make the config block survive being written out by @jdx in #832
(spec) apply default_subcommand only at the root by @jdx in #850
(spec) split a clap default by the delimiter clap splits it by by @jdx in #901
(spec) rank a subcommand name above another command's alias by @jdx in #967
(spec) preserve clap value count bounds by @jdx in #1032
(spec) deduplicate derived completers by @jdx in #1072
(spec) canonicalize derived kdl by @jdx in #1095

🚜 Refactor

(deps) breaking stop shipping features and crates nobody uses by @jdx in #1185
(deps) drop heck from usage-derive by @jdx in #1187
(deps) take expr-lang without the builtins a spec cannot reach by @jdx in #1191

📚 Documentation

(plan) tick landed clap gaps and stop quoting vector counts by @jdx in #1027
correct current Rust limitations by @jdx in #1029
audit 6.x release documentation by @jdx in #1084
add third-party license notices by @jdx in #1174

⚡ Performance

(derive) fill the partial through &mut instead of returning it by @jdx in #980
(derive) hold one subcommand's partial, not every subcommand's by @jdx in #981
(derive) drop proc-macro-crate transitive deps by @jdx in #1042

🧪 Testing

(clap) preserve choices in external adopter probes by @jdx in #1157
(corpus) pin what completes where the cursor is by @jdx in #998
(derive) cover verbatim doc compatibility by @jdx in #1092
(docs) preserve fleet footer spacing by @jdx in #1142
(fleet) refresh typed adopter fixtures by @jdx in #1115
(parse) cover mounted command discovery by @jdx in #1131
(parse) add clap micro-conformance by @jdx in #1133
(spec) import the argv questions clap's suite answers and ours did not by @jdx in #926
(spec) verify portable parser settings by @jdx in #1053

🛡️ Security

(config) resolve settings from layers, with provenance by @jdx in #849
(config) read the environment as a layer by @jdx in #867
(config) give a deprecation notice from anywhere along a rename chain by @jdx in #893
(derive) keep parsed fields live for lints by @jdx in #1138
(docs) render the config block by @jdx in #837
(go) render the page -h prints, matching usage-lib on all 211 of mise's by @jdx in #974
(go) render --help too, matching usage-lib on all 211 of mise's long pages by @jdx in #975
(parse) require exact command and flag names by @jdx in #1096
(spec) the config vocabulary by @jdx in #835

🔍 Other Changes

(docs) remove stale mise spec fixture by @jdx in #1200
(perf) say when the clap ratio slides, and record why the derive is stricter by @jdx in #996
agent/complete files by @jdx in #883

📦️ Dependency Updates

update rust crate syn to v3 by @renovate[bot] in #808
update rust crate toml to v1 by @renovate[bot] in #1016