Repository navigation
Optique 1.4.0: Default commands, Markdown references, and more focused help #1139
dahlia
announced in
Announcements
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Optique is a type-safe combinatorial CLI parser for TypeScript built from composable parser functions. Parser definitions drive runtime parsing, help and completion output, and the inferred value types that handlers receive.
In Optique 1.4.0, a CLI can accept
app src/main.tsas shorthand forapp run src/main.tswithout rewriting its arguments. You can also publish a linked Markdown reference for your command tree and show just the relevant command's usage when parsing fails. For everyday invocations, short options can take attached values such as-n5.A default action alongside named commands
If most users run the same action, asking them to type its name every time gets old. But if you insert
runinto the argument list yourself, you have to decide which names belong to subcommands or built-in help, and root help and completion still don't describe the implicit action. The default command option proposed in #1103 and implemented in #1138 letsrunProgram()handle that routing.app src/main.tsandapp run src/main.tsselect the same handler.app buildselects the registered command, even if the rest of the invocation fails to parse. To pass a file literally namedbuildto the default, useapp -- build. Enabled help, version, and completion entry points take precedence over the fallback. Root help includes the default command's arguments and options, and shell completion can suggest its positional values.For file-based discovery, mark the command definition with
default: trueinstead. This is opt-in, and a default cannot coexist with a separate root command.A Markdown reference for the whole CLI
--helpis useful when you already know which command to ask about. It is less convenient when you want to browse an unfamiliar CLI or publish its entire command tree as one document. @sergei-dyshel requested that use case in #1025. The Markdown reference renderer added in #1095 takes command pages and generates one file with a linked contents list and a section for each command.The collector reads metadata from supported built-in parsers. It does not run the parser or its callbacks, and by default it reports unsupported visible scopes as errors rather than silently omitting them. You can supply your own pages or replacements instead. The renderer doesn't add a
docscommand. You decide whether to generate the file at build time or expose it at runtime, and which runner-added help, version, or completion entry points to document.Help that stays on the command you ran
If
app config set --port invalidfails, a synopsis that lists every other command pushes the useful part of the error farther down. The command-scoped usage option from #1086, implemented in #1093, narrows the usage line using the command path already recorded by the failed parse.The usage for
config setretains relevant parent options and leaves outserve. Root usage remains the default and the fallback if the runner can't reliably identify a visible command. The option only affects usage above errors, not full help, the error message, or the exit code.Bare command groups can show their command menu without requiring
--help. Sethelp.bareGroupto"namespace"for groups with no action of their own, or"always"to show help in place of running a parent command. The default is still"never". The opt-in policy in #1027 came from a workaround in bestofjs/bestofjs#513.You can also turn on environment variable names in help with
showEnvironment, without repeating the names frombindEnv()in option descriptions. @TomerAberbach reported that duplication in #969; #986 added the shared help and man page support, and #987 covers environment bindings that have no CLI option or argument of their own. This documents names, not values, and is off by default.Other changes
-n5now works like-n 5, and-xn5like-x -n 5when-xis a flag. A value-taking short option consumes the rest of the token literally, so-n=5passes=5, not5. A reachable full single-dash option name still takes precedence, and completion works for attached values too. Thanks to @sergei-dyshel for raising this in Support for single-character option followed by argument without space (e.g. "-n2") #965; the change landed in Support attached short-option values #981.autocompleteandautocomplete-multiselect; Inquirer.js can fetch results as you type withsearch. To fetch a list once before the prompt opens, pass a resolver toderivePromptConfig(). The resolver runs only if Optique needs to prompt, so a value supplied on the command line skips the fetch. Clack can show a spinner while the resolver runs. Thanks to @adworacz for the async choices request in async resolution ofoptionsfor Clack prompts #964. (Derive prompt configurations without dependency sources #979, Show pending state while derived prompt configuration resolves #1018, Make selection prompts searchable #1019)withSuggestions()attaches completion candidates to an existing value parser without changing what it accepts. Candidates replace the parser's own suggestions by default; setincludeExisting: trueto keep both. (Attach completion suggestions to existing value parsers #1111, AddwithSuggestions()to attach completion candidates to value parsers #1114)normalizeInput()cleans raw CLI and environment strings before validation; thekeyoption onchoice()compares under a custom rule while returning the declared spelling. Thanks to @TomerAberbach for the normalization request in Value parsers have no hook to normalize the input before validation #971. (Allow custom matching keys forchoice()#998, Normalize raw input before value parsing #999, Matchchoice()values with custom keys #1000)helpSectionscan separate command and option lists without adding headings to pages with no visible commands.showAliasescan display aliases in help without changing canonical usage lines. (Allow easy grouping of subcommands (only) #972, Make command and option help headings opt-in #983, Support for command aliases in help/docs #1002, Show command aliases in help on request #1005)Bug fixes
optionsfor Clack prompts #964, Derive prompt configurations without dependency sources #979)passThrough()no longer hides the original missing-value error for a known option in the affected parser compositions. (Share branch selection rules between parsing and arbitration #994, Keep option arbitration aligned with parsing #996)Acknowledgments
Upgrading
Upgrade any other Optique packages you use to v1.4.0 as well, including @optique/discover and @optique/man for the examples above. No public API was removed, but a few behaviors are worth checking when upgrading. Man pages, including
optique-manoutput, now label defaults as(default: value)instead of[value]; passshowDefault: { prefix: " [", suffix: "]" }to the generator to restore the old format. Usage and help snapshots may also need updating. If a custom mismatch callback does work besides formatting an error, move that work elsewhere: #997 defers diagnostics until they're needed, so discarded failures may no longer call it.See CHANGES.md for the complete changelog.
All reactions