Behaviour of usage 6.12.0–7.3.0 which kongusage depends on. Undocumented behaviour is marked so: it may change in any release.
- Completion:
usage complete-word, scripts ofusage generate completion, and mise, which completes by the same code as theusageCLI of its usage-lib version. - Documentation:
usage generate md,usage generate manpage. - Parsing:
usage explain, scripts run by usage, mise tasks withoutraw_args. - Compatibility:
usage diffcompares two specs by their parsing semantics and exits 1 on a breaking change.
usage-lib refuses a spec with an unknown node or property, so no consumer can use it at all.
mount run="<command>" takes the spec of a command from the output of <command>.
- The command runs by
sh -cin the current directory of the shell, with stdin closed, and with__USAGE=<usage-lib version>in its environment.__USAGEis documented forcomplete run=only (undocumented formount). - Only the root command of the mounted spec is merged into the mounting command
(undocumented).
Spec-level nodes have no effect there:
default_subcommand*,disable_help, rootunknown_flags,unknown_env,version,about, top-levelcompleteand the like. Root flags, positionals, subcommands, properties of commands (disable_help_flag,subcommand_required, …), inlinecompleteandchoiceswork.
usage generate completion <shell> <bin> --usage-cmd "<bin> --usage-spec"
generates a script which runs the --usage-cmd command in the user's shell on every Tab,
without __USAGE in its environment.
With --cache-key <key> (e.g. the version of the CLI) the command runs once per key.
The spec is used as a root spec there, so spec-level nodes take effect.
requires, overrides and conflicts name one flag as a property (requires="--b")
or several flags as a child node (requires "--b" "--c", since 6.0.0).
A property naming several flags (requires="--b --c") is taken as one bogus flag name
up to 7.1.4 and refused since 7.1.5.
A value without its own complete and choices is completed by its value name,
in any case (undocumented):
<dir> completes directories, <COMMAND> commands on PATH,
<HOSTNAME> hosts, <USERNAME> users, <URL>, <EMAIL> and <NONE> nothing,
any other name files.
The name of a positional is used the same way (arg "[url]" completes nothing).
complete type="none"completes nothing.complete type="unknown"completes files whatever the value name is.complete type="dir"completes directories, but files when no directory matches, contrary to the docs.
-h,--helpand-?exist on every command;disable_helpremoves them everywhere,disable_help_flagon one command only.usage difftakes--helpas accepted unless the command hasdisable_help_flag, ignoringdisable_helpand a declared--help(undocumented).-Vand--versionexist on the root when the spec hasversion.- Since 7.2.0, usage completes
-h,--help,-Vand--versionunless declared flags use them. - Terminal help of a command with subcommands lists a
helpsubcommand which the parser refuses (jdx/usage#1636).disable_helpdoes not remove it, contrary to the docs;disable_help_subcommanddoes, on one command only.