usage

.mise.toml

@@ -3,6 +3,7 @@
 min_version = "2024.1.1"
 [env]
 _.file = [".env"]
+_.path = ["./target/debug"]
 FOO = "bar"
 FOO_NUM = 1
 THIS_PROJECT = "{{config_root}}-{{cwd}}"
@@ -30,8 +31,8 @@ run = "cargo clean"
 [tasks.build]
 alias = "b"
 run = "cargo build --color always --all-features"
-sources = ["Cargo.*", "src/**/*.rs"]
-outputs = ["target/debug/mise"]
+#sources = ["Cargo.*", "src/**/*.rs"]
+#outputs = ["target/debug/mise"]
 
 [tasks.ci]
 depends = [
@@ -40,30 +41,35 @@ depends = [
     "test"
 ]
 
-[tasks."render:completions"]
+[tasks."render:usage"]
 depends = ["build"]
+env = { CLICOLOR_FORCE = "0" }
+run = "mise usage > mise.usage.kdl"
+
+[tasks."render:completions"]
+depends = ["build", "render:usage"]
 env = { NO_COLOR = "1" }
 run = '''
 #!/usr/bin/env bash
 set -xeuo pipefail
-target/debug/mise render-completion bash > completions/mise.bash
-target/debug/mise render-completion zsh > completions/_mise
-target/debug/mise render-completion fish > completions/mise.fish
+mise render-completion bash > completions/mise.bash
+mise render-completion zsh > completions/_mise
+mise render-completion fish > completions/mise.fish
 '''
 
 [tasks."render:mangen"]
 depends = ["build"]
 env = { NO_COLOR = "1" }
-run = "target/debug/mise render-mangen"
+run = "mise render-mangen"
 
 [tasks."render:help"]
 depends = ["build"]
 env = { NO_COLOR = "1" }
 run = [
-  "target/debug/mise render-help",
+  "mise render-help",
   "mise x node@latest -- npx markdown-magic",
 ]
-sources = ["target/debug/mise"]
+sources = ["mise"]
 outputs = ["README.md"]
 
 [tasks.render]

Cargo.toml

@@ -14,6 +14,7 @@ categories = ["command-line-utilities"]
 include = [
     "src/**/*.rs",
     "src/plugins/core/assets/**",
+    "src/assets/**",
     "/completions/*",
     "/Cargo.lock",
     "/LICENSE",
@@ -106,6 +107,8 @@ walkdir = "2.4.0"
 which = "6.0.0"
 zip = { version = "0.6.6", default-features = false, features = ["deflate"] }
 
+usage-lib = { path = './usage', features = ["clap"] }
+
 [target.'cfg(unix)'.dependencies]
 exec = "0.3.1"
 

completions/_mise

@@ -54,6 +54,7 @@ _mise() {
         (remove|rm|uninstall) __mise_uninstall_cmd && ret=0 ;;
         (unset) __mise_unset_cmd && ret=0 ;;
         (up|upgrade) __mise_upgrade_cmd && ret=0 ;;
+        (usage) __mise_usage_cmd && ret=0 ;;
         (u|use) __mise_use_cmd && ret=0 ;;
         (v|version) __mise_version_cmd && ret=0 ;;
         (w|watch) __mise_watch_cmd && ret=0 ;;
@@ -614,6 +615,7 @@ __mise_set_cmd() {
 (( $+functions[__mise_settings_cmd] )) ||
 __mise_settings_cmd() {
   _arguments -s -S \
+    '--keys[Only display key names for each setting]' \
     '(-C --cd)'{-C,--cd}'=[Change directory before running command]:cd:_directories' \
     '(-q --quiet)'{-q,--quiet}'[Suppress non-error messages]' \
     '*'{-v,--verbose}'[Show extra output (use -vv for even more)]' \
@@ -647,6 +649,7 @@ __mise_settings_get_cmd() {
 (( $+functions[__mise_settings_ls_cmd] )) ||
 __mise_settings_ls_cmd() {
   _arguments -s -S \
+    '--keys[Only display key names for each setting]' \
     '(-C --cd)'{-C,--cd}'=[Change directory before running command]:cd:_directories' \
     '(-q --quiet)'{-q,--quiet}'[Suppress non-error messages]' \
     '*'{-v,--verbose}'[Show extra output (use -vv for even more)]' \
@@ -845,6 +848,14 @@ __mise_upgrade_cmd() {
     '*'{-v,--verbose}'[Show extra output (use -vv for even more)]' \
     '(-y --yes)'{-y,--yes}'[Answer yes to all confirmation prompts]'
 }
+(( $+functions[__mise_usage_cmd] )) ||
+__mise_usage_cmd() {
+  _arguments -s -S \
+    '(-C --cd)'{-C,--cd}'=[Change directory before running command]:cd:_directories' \
+    '(-q --quiet)'{-q,--quiet}'[Suppress non-error messages]' \
+    '*'{-v,--verbose}'[Show extra output (use -vv for even more)]' \
+    '(-y --yes)'{-y,--yes}'[Answer yes to all confirmation prompts]'
+}
 (( $+functions[__mise_use_cmd] )) ||
 __mise_use_cmd() {
   _arguments -s -S \
@@ -939,6 +950,7 @@ __mise_cmds() {
     {remove,rm,uninstall}':Removes runtime versions'
     'unset:Remove environment variable(s) from the config file'
     {up,upgrade}':Upgrades outdated tool versions'
+    'usage:Generate usage spec'
     {u,use}':Install tool version and add it to config'
     'version:Show mise version'
     {w,watch}':\[experimental\] Run a tasks watching for changes'

completions/mise.bash

@@ -183,6 +183,9 @@ _mise() {
             mise,upgrade)
                 cmd="mise__upgrade"
                 ;;
+            mise,usage)
+                cmd="mise__usage"
+                ;;
             mise,use)
                 cmd="mise__use"
                 ;;
@@ -441,6 +444,9 @@ _mise() {
             mise__help,upgrade)
                 cmd="mise__help__upgrade"
                 ;;
+            mise__help,usage)
+                cmd="mise__help__usage"
+                ;;
             mise__help,use)
                 cmd="mise__help__use"
                 ;;
@@ -718,7 +724,7 @@ _mise() {
 
     case "${cmd}" in
         mise)
-            opts="-C -q -v -y -h -V --cd --debug --log-level --quiet --trace --verbose --yes --help --version activate alias asdf bin-paths cache completion config current deactivate direnv doctor env exec global hook-env hook-not-found implode install latest link local ls ls-remote outdated plugins prune reshim run self-update set settings shell sync tasks trust uninstall upgrade unset use version watch where which render-completion render-help render-mangen help"
+            opts="-C -q -v -y -h -V --cd --debug --log-level --quiet --trace --verbose --yes --help --version activate alias asdf bin-paths cache completion config current deactivate direnv doctor env exec global hook-env hook-not-found implode install latest link local ls ls-remote outdated plugins prune reshim run self-update set settings shell sync tasks trust uninstall unset upgrade usage use version watch where which render-completion render-help render-mangen help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -1852,7 +1858,7 @@ _mise() {
             return 0
             ;;
         mise__help)
-            opts="activate alias asdf bin-paths cache completion config current deactivate direnv doctor env exec global hook-env hook-not-found implode install latest link local ls ls-remote outdated plugins prune reshim run self-update set settings shell sync tasks trust uninstall upgrade unset use version watch where which render-completion render-help render-mangen help"
+            opts="activate alias asdf bin-paths cache completion config current deactivate direnv doctor env exec global hook-env hook-not-found implode install latest link local ls ls-remote outdated plugins prune reshim run self-update set settings shell sync tasks trust uninstall unset upgrade usage use version watch where which render-completion render-help render-mangen help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -2817,6 +2823,20 @@ _mise() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
+        mise__help__usage)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
         mise__help__use)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
@@ -3624,7 +3644,7 @@ _mise() {
             return 0
             ;;
         mise__render__completion)
-            opts="-s -C -q -v -y -h --shell --cd --debug --log-level --quiet --trace --verbose --yes --help bash elvish fish powershell zsh"
+            opts="-s -C -q -v -y -h --shell --usage --cd --debug --log-level --quiet --trace --verbose --yes --help bash elvish fish powershell zsh"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -3891,7 +3911,7 @@ _mise() {
             return 0
             ;;
         mise__settings)
-            opts="-C -q -v -y -h --cd --debug --log-level --quiet --trace --verbose --yes --help get ls set unset help"
+            opts="-C -q -v -y -h --keys --cd --debug --log-level --quiet --trace --verbose --yes --help get ls set unset help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -4039,7 +4059,7 @@ _mise() {
             return 0
             ;;
         mise__settings__ls)
-            opts="-C -q -v -y -h --cd --debug --log-level --quiet --trace --verbose --yes --help"
+            opts="-C -q -v -y -h --keys --cd --debug --log-level --quiet --trace --verbose --yes --help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -4752,6 +4772,38 @@ _mise() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
+        mise__usage)
+            opts="-C -q -v -y -h --cd --debug --log-level --quiet --trace --verbose --yes --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --cd)
+                    COMPREPLY=()
+                    if [[ "${BASH_VERSINFO[0]}" -ge 4 ]]; then
+                        compopt -o plusdirs
+                    fi
+                    return 0
+                    ;;
+                -C)
+                    COMPREPLY=()
+                    if [[ "${BASH_VERSINFO[0]}" -ge 4 ]]; then
+                        compopt -o plusdirs
+                    fi
+                    return 0
+                    ;;
+                --log-level)
+                    COMPREPLY=($(compgen -W "error warn info debug trace" -- "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
         mise__use)
             opts="-f -g -e -j -p -C -q -v -y -h --force --fuzzy --global --env --jobs --raw --remove --path --pin --cd --debug --log-level --quiet --trace --verbose --yes --help [TOOL@VERSION]..."
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then

completions/mise.fish

@@ -5,7 +5,7 @@ complete -kxc mise -s C -l cd -a "(__fish_complete_directories)" -d 'Change dire
 complete -kxc mise -s q -l quiet -d 'Suppress non-error messages'
 complete -kxc mise -s v -l verbose -d 'Show extra output (use -vv for even more)'
 complete -kxc mise -s y -l yes -d 'Answer yes to all confirmation prompts'
-set -l others activate alias bin-paths cache completion config current deactivate direnv doctor env exec implode install latest link ls ls-remote outdated plugins prune reshim run self-update set settings shell sync tasks trust uninstall unset upgrade use version watch where which
+set -l others activate alias bin-paths cache completion config current deactivate direnv doctor env exec implode install latest link ls ls-remote outdated plugins prune reshim run self-update set settings shell sync tasks trust uninstall unset upgrade usage use version watch where which
 complete -xc mise -n "not $fssf $others" -a activate -d 'Initializes mise in the current shell session'
 complete -xc mise -n "not $fssf $others" -a alias -d 'Manage aliases'
 complete -xc mise -n "not $fssf $others" -a bin-paths -d 'List all the active runtime bin paths'
@@ -39,6 +39,7 @@ complete -xc mise -n "not $fssf $others" -a trust -d 'Marks a config file as tru
 complete -xc mise -n "not $fssf $others" -a uninstall -d 'Removes runtime versions'
 complete -xc mise -n "not $fssf $others" -a unset -d 'Remove environment variable(s) from the config file'
 complete -xc mise -n "not $fssf $others" -a upgrade -d 'Upgrades outdated tool versions'
+complete -xc mise -n "not $fssf $others" -a usage -d 'Generate usage spec'
 complete -xc mise -n "not $fssf $others" -a use -d 'Install tool version and add it to config'
 complete -xc mise -n "not $fssf $others" -a version -d 'Show mise version'
 complete -xc mise -n "not $fssf $others" -a watch -d '[experimental] Run a tasks watching for changes'
@@ -241,6 +242,7 @@ complete -kxc mise -n "$fssf set" -l file -a "(__fish_complete_path)" -d 'The TO
 complete -kxc mise -n "$fssf set" -s g -l global -d 'Set the environment variable in the global config file'
 
 # settings
+complete -kxc mise -n "$fssf settings" -l keys -d 'Only display key names for each setting'
 set -l others get ls set unset
 complete -xc mise -n "$fssf settings; and not $fssf $others" -a get -d 'Show a current setting'
 complete -xc mise -n "$fssf settings; and not $fssf $others" -a ls -d 'Show current settings'
@@ -251,6 +253,7 @@ complete -xc mise -n "$fssf settings; and not $fssf $others" -a unset -d 'Clears
 complete -kxc mise -n "$fssf settings; and $fssf get" -a "(__mise_settings)" -d 'The setting to show'
 
 # settings ls
+complete -kxc mise -n "$fssf settings; and $fssf ls" -l keys -d 'Only display key names for each setting'
 
 # settings set
 complete -kxc mise -n "$fssf settings; and $fssf set" -a "(__mise_settings)" -d 'The setting to set'
@@ -337,6 +340,8 @@ complete -kxc mise -n "$fssf upgrade" -s j -l jobs -d 'Number of jobs to run in
 complete -kxc mise -n "$fssf upgrade" -l raw -d 'Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1'
 complete -kxc mise -n "$fssf upgrade" -a "(__mise_tool_versions)" -d 'Tool(s) to upgrade'
 
+# usage
+
 # use
 complete -kxc mise -n "$fssf use" -s e -l env -d 'Modify an environment-specific config file like .mise.<env>.toml'
 complete -kxc mise -n "$fssf use" -s f -l force -d 'Force reinstall even if already installed'