From 90703477cfce6d7d4fc273a7687f2baa73bc90f1 Mon Sep 17 00:00:00 2001 From: Jeff Dickey <216188+jdx@users.noreply.github.com> Date: Sat, 13 Jan 2024 21:23:35 -0600 Subject: [PATCH] wip --- Cargo.lock | 4 +- cli/src/cli/generate/markdown.rs | 28 +- examples/MISE_README.md | 865 ++++++++++++++++++++++++++++++- examples/mise.gen.usage.kdl | 150 +++--- src/parse/cmd.rs | 24 + src/parse/spec.rs | 29 +- 6 files changed, 1018 insertions(+), 82 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 6375bbd..19b8575 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1554,9 +1554,9 @@ checksum = "dff9641d1cd4be8d1a070daf9e3773c5f67e78b4d9d42263020c057706765c04" [[package]] name = "xx" -version = "0.2.0" +version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3bb55e119e08a15c8a896dbf586e2517ff1d84efa83b7940747582e264531817" +checksum = "846a62538e6f30c0b450a936b9c711a11579803d41e6b4f959318693a7041bdc" dependencies = [ "miette", "thiserror", diff --git a/cli/src/cli/generate/markdown.rs b/cli/src/cli/generate/markdown.rs index a3b38f6..f0ccf29 100644 --- a/cli/src/cli/generate/markdown.rs +++ b/cli/src/cli/generate/markdown.rs @@ -159,7 +159,7 @@ const USAGE_OVERVIEW_TEMPLATE: &str = r#" ``` "#; -static CONFIG_TEMPLATE: &str = r#" +const CONFIG_TEMPLATE: &str = r#" ### `!KEY!` !ENV! @@ -180,13 +180,27 @@ const COMMANDS_INDEX_TEMPLATE: &str = r#" const COMMANDS_TEMPLATE: &str = r#" ### `{{ cmd.full_cmd | join(sep=" ") }}` +{% if cmd.before_long_help -%} +{{ cmd.before_long_help }} +{% elif cmd.before_help -%} +{{ cmd.before_help }} +{% endif -%} + +{% if cmd.aliases -%} +#### Aliases + +{% for alias in cmd.aliases -%} +* `{{ alias }}` +{% endfor -%} +{% endif -%} + {% if cmd.args -%} #### Args {% for arg in cmd.args -%} * `{{ arg.usage }}` – {{ arg.long_help | default(value=arg.help) }} {% endfor -%} -{% endif -%} +{% endif %} {% if cmd.flags -%} #### Flags @@ -196,12 +210,16 @@ const COMMANDS_TEMPLATE: &str = r#" {% endfor -%} {% endif -%} -{% if cmd.help -%} +{% if cmd.long_help -%} +{{ cmd.long_help }} +{% elif cmd.help -%} {{ cmd.help }} {% endif -%} -{% if cmd.long_help -%} -{{ cmd.long_help }} +{% if cmd.after_long_help -%} +{{ cmd.after_long_help }} +{% elif cmd.after_help -%} +{{ cmd.after_help }} {% endif -%} "#; diff --git a/examples/MISE_README.md b/examples/MISE_README.md index 88d5c36..84f083a 100644 --- a/examples/MISE_README.md +++ b/examples/MISE_README.md @@ -9,7 +9,7 @@ ## Usage ```bash -mise.usage.kdl [flags] [args] +mise [flags] [args] ``` @@ -103,6 +103,7 @@ foooooooo * [`sync node`](#sync-node) * [`sync python`](#sync-python) * [`task`](#task) +* [`task deps`](#task-deps) * [`task edit`](#task-edit) * [`task ls`](#task-ls) * [`task run`](#task-run) @@ -127,19 +128,51 @@ foooooooo #### Args * `[SHELL_TYPE]` – Shell type to generate the script for + + #### Flags * `-s,--shell ` – Shell type to generate the script for * `--status` – Show "mise: @" message when changing directories * `-q,--quiet` – Suppress non-error messages +Initializes mise in the current shell session + +This should go into your shell's rc file. +Otherwise, it will only take effect in the current session. +(e.g. ~/.zshrc, ~/.bashrc) + +This is only intended to be used in interactive sessions, not scripts. +mise is only capable of updating PATH when the prompt is displayed to the user. +For non-interactive use-cases, use shims instead. + +Typically this can be added with something like the following: + + echo 'eval "$(mise activate)"' >> ~/.zshrc + +However, this requires that "mise" is in your PATH. If it is not, you need to +specify the full path like this: + + echo 'eval "$(/path/to/mise activate)"' >> ~/.zshrc +Examples: + $ eval "$(mise activate bash)" + $ eval "$(mise activate zsh)" + $ mise activate fish | source + $ execx($(mise activate xonsh)) + ### `alias` +#### Aliases + +* `a` + + #### Flags * `-p,--plugin ` – filter aliases by plugin * `--no-header` – Don't show table header +Manage aliases ### `alias get` @@ -150,18 +183,48 @@ foooooooo * `` – The alias to show +Show an alias for a plugin + +This is the contents of an alias. entry in ~/.config/mise/config.toml +Examples: + $ mise alias get node lts-hydrogen + 20.0.0 + + + ### `alias ls` +#### Aliases + +* `list` #### Args * `[PLUGIN]` – Show aliases for + + #### Flags * `--no-header` – Don't show table header +List aliases +Shows the aliases that can be specified. +These can come from user config or from plugins in `bin/list-aliases`. + +For user config, aliases are defined like the following in `~/.config/mise/config.toml`: + + [alias.node] + lts = "20.0.0" +Examples: + $ mise aliases + node lts-hydrogen 20.0.0 + ### `alias set` +#### Aliases + +* `add` +* `create` #### Args * `` – The plugin to set the alias for @@ -169,58 +232,124 @@ foooooooo * `` – The value to set the alias to +Add/update an alias for a plugin + +This modifies the contents of ~/.config/mise/config.toml +Examples: + $ mise alias set node lts-hydrogen 18.0.0 + + + ### `alias unset` +#### Aliases + +* `rm` +* `remove` +* `delete` +* `del` #### Args * `` – The plugin to remove the alias from * `` – The alias to remove +Clears an alias for a plugin + +This modifies the contents of ~/.config/mise/config.toml +Examples: + $ mise alias unset node lts-hydrogen + + + ### `bin-paths` +List all the active runtime bin paths + + ### `cache` +Manage the mise cache + +Run `mise cache` with no args to view the current cache directory. + + ### `cache clear` +#### Aliases + +* `c` #### Args * `[PLUGIN]...` – Plugin(s) to clear cache for e.g.: node, python +Deletes all cache files in mise + + ### `completion` #### Args * `[SHELL]` – Shell type to generate completions for + + #### Flags * `-s,--shell ` – Shell type to generate completions for +Generate shell completions +Examples: + $ mise completion bash > /etc/bash_completion.d/mise + $ mise completion zsh > /usr/local/share/zsh/site-functions/_mise + $ mise completion fish > ~/.config/fish/completions/mise.fish + ### `config` +#### Aliases + +* `cfg` + + #### Flags * `--no-header` – Do not print table header +[experimental] Manage config files ### `config ls` + + #### Flags * `--no-header` – Do not print table header +[experimental] List config files currently in use +Examples: + $ mise config ls + ### `config generate` +#### Aliases + +* `g` + + #### Flags * `-o,--output ` – Output to file instead of stdout +[experimental] Generate an .mise.toml file +Examples: + $ mise cf generate > .mise.toml + $ mise cf generate --output=.mise.toml + ### `current` @@ -230,60 +359,171 @@ foooooooo * `[PLUGIN]` – Plugin to show versions of e.g.: ruby, node, cargo:eza, npm:prettier, etc +Shows current active and installed runtime versions + +This is similar to `mise ls --current`, but this only shows the runtime +and/or version. It's designed to fit into scripts more easily. +Examples: + # outputs `.tool-versions` compatible format + $ mise current + python 3.11.0 3.10.0 + shfmt 3.6.0 + shellcheck 0.9.0 + node 20.0.0 + + $ mise current node + 20.0.0 + + # can output multiple versions + $ mise current python + 3.11.0 3.10.0 + + + ### `deactivate` +Disable mise for current shell session + +This can be used to temporarily disable mise in a shell session. +Examples: + $ mise deactivate bash + $ mise deactivate zsh + $ mise deactivate fish + $ execx($(mise deactivate xonsh)) + + + ### `direnv` +Output direnv function to use mise inside direnv + +See https://mise.rtx.dev/direnv.html for more information + +Because this generates the legacy files based on currently installed plugins, +you should run this command after installing new plugins. Otherwise +direnv may not know to update environment variables when legacy file versions change. + + ### `direnv activate` +Output direnv function to use mise inside direnv + +See https://mise.jdx.dev/direnv.html for more information + +Because this generates the legacy files based on currently installed plugins, +you should run this command after installing new plugins. Otherwise +direnv may not know to update environment variables when legacy file versions change. +Examples: + $ mise direnv activate > ~/.config/direnv/lib/use_mise.sh + $ echo 'use mise' > .envrc + $ direnv allow + + + ### `doctor` +Check mise installation for possible problems. +Examples: + $ mise doctor + [WARN] plugin node is not installed + + + ### `env` +#### Aliases + +* `e` #### Args * `[TOOL@VERSION]...` – Tool(s) to use + + #### Flags * `-s,--shell ` – Shell type to generate environment variables for * `-J,--json` – Output in JSON format +Exports env vars to activate mise a single time + +Use this if you don't want to permanently install mise. It's not necessary to +use this if you have `mise activate` in your shell rc file. +Examples: + $ eval "$(mise env -s bash)" + $ eval "$(mise env -s zsh)" + $ mise env -s fish | source + $ execx($(mise env -s xonsh)) + ### `exec` +#### Aliases + +* `x` #### Args * `[TOOL@VERSION]...` – Tool(s) to start e.g.: node@20 python@3.10 * `[COMMAND]...` – Command string to execute (same as --command) + + #### Flags * `-c,--command ` – Command string to execute * `-j,--jobs ` – Number of jobs to run in parallel [default: 4] * `--raw` – Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 +Execute a command with tool(s) set + +use this to avoid modifying the shell session or running ad-hoc commands with mise tools set. + +Tools will be loaded from .mise.toml/.tool-versions, though they can be overridden with args +Note that only the plugin specified will be overridden, so if a `.tool-versions` file +includes "node 20" but you run `mise exec python@3.11`; it will still load node@20. + +The "--" separates runtimes from the commands to pass along to the subprocess. +Examples: + $ mise exec node@20 -- node ./app.js # launch app.js using node-20.x + $ mise x node@20 -- node ./app.js # shorter alias + + # Specify command as a string: + $ mise exec node@20 python@3.11 --command "node -v && python -V" + + # Run a command in a different directory: + $ mise x -C /path/to/project node@20 -- node ./app.js + ### `implode` + + #### Flags * `--config` – Also remove config directory * `-n,--dry-run` – List directories that would be removed without actually removing them +Removes mise CLI and all related data + +Skips config directory by default. ### `install` +#### Aliases + +* `i` #### Args * `[TOOL@VERSION]...` – Tool(s) to install e.g.: node@20 + + #### Flags * `-f,--force` – Force reinstall even if already installed @@ -291,6 +531,20 @@ foooooooo [default: 4] * `--raw` – Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 * `-v,--verbose` – Show installation output +Install a tool version + +This will install a tool version to `~/.local/share/mise/installs//` +It won't be used simply by being installed, however. +For that, you must set up a `.mise.toml`/`.tool-version` file manually or with `mise use`. +Or you can call a tool version explicitly with `mise exec @ -- `. + +Tools will be installed in parallel. To disable, set `--jobs=1` or `MISE_JOBS=1` +Examples: + $ mise install node@20.0.0 # install specific node version + $ mise install node@20 # install fuzzy node version + $ mise install node # install version specified in .tool-versions or .mise.toml + $ mise install # installs everything specified in .tool-versions or .mise.toml + ### `latest` @@ -299,28 +553,62 @@ foooooooo * `` – Tool to get the latest version of * `[ASDF_VERSION]` – The version prefix to use when querying the latest version same as the first argument after the "@" used for asdf compatibility + + #### Flags * `-i,--installed` – Show latest installed instead of available version +Gets the latest available version for a plugin +Examples: + $ mise latest node@20 # get the latest version of node 20 + 20.0.0 + + $ mise latest node # get the latest stable version of node + 20.0.0 + ### `link` +#### Aliases + +* `ln` #### Args * `` – Tool name and version to create a symlink for * `` – The local path to the tool version e.g.: ~/.nvm/versions/node/v20.0.0 + + #### Flags * `-f,--force` – Overwrite an existing tool version if it exists +Symlinks a tool version into mise + +Use this for adding installs either custom compiled outside +mise or built with a different tool. +Examples: + # build node-20.0.0 with node-build and link it into mise + $ node-build 20.0.0 ~/.nodes/20.0.0 + $ mise link node@20.0.0 ~/.nodes/20.0.0 + + # have mise use the python version provided by Homebrew + $ brew install node + $ mise link node@brew $(brew --prefix node) + $ mise use node@brew + ### `ls` +#### Aliases + +* `list` #### Args * `[PLUGIN]...` – Only show tool versions from [PLUGIN] + + #### Flags * `-p,--plugin ` – @@ -332,6 +620,32 @@ e.g.: ~/.nvm/versions/node/v20.0.0 * `-m,--missing` – Display missing tool versions * `--prefix ` – Display versions matching this prefix * `--no-header` – Don't display headers +List installed and/or currently selected tool versions +Examples: + $ mise ls + node 20.0.0 ~/src/myapp/.tool-versions latest + python 3.11.0 ~/.tool-versions 3.10 + python 3.10.0 + + $ mise ls --current + node 20.0.0 ~/src/myapp/.tool-versions 20 + python 3.11.0 ~/.tool-versions 3.11.0 + + $ mise ls --json + { + "node": [ + { + "version": "20.0.0", + "install_path": "/Users/jdx/.mise/installs/node/20.0.0", + "source": { + "type": ".mise.toml", + "path": "/Users/jdx/.mise.toml" + } + } + ], + "python": [...] + } + ### `ls-remote` @@ -341,9 +655,28 @@ e.g.: ~/.nvm/versions/node/v20.0.0 * `[TOOL@VERSION]` – Plugin to get versions for * `[PREFIX]` – The version prefix to use when querying the latest version same as the first argument after the "@" + + #### Flags * `--all` – Show all installed plugins and versions +List runtime versions available for install + +note that the results are cached for 24 hours +run `mise cache clean` to clear the cache and get fresh results +Examples: + $ mise ls-remote node + 18.0.0 + 20.0.0 + + $ mise ls-remote node@20 + 20.0.0 + 20.1.0 + + $ mise ls-remote node 20 + 20.0.0 + 20.1.0 + ### `outdated` @@ -355,8 +688,26 @@ e.g.: node@20 python@3.10 If not specified, all tools in global and local configs will be shown +Shows outdated tool versions +Examples: + $ mise outdated + Plugin Requested Current Latest + python 3.11 3.11.0 3.11.1 + node 20 20.0.0 20.1.0 + + $ mise outdated node + Plugin Requested Current Latest + node 20 20.0.0 20.1.0 + + + ### `plugins` +#### Aliases + +* `p` + + #### Flags * `-a,--all` – list all available remote plugins @@ -372,10 +723,16 @@ to show core and user plugins e.g.: https://github.com/asdf-vm/asdf-node.git * `--refs` – Show the git refs for each plugin e.g.: main 1234abc +Manage plugins ### `plugins install` +#### Aliases + +* `i` +* `a` +* `add` #### Args * `[NEW_PLUGIN]` – The name of the plugin to install @@ -383,6 +740,8 @@ e.g.: node, ruby Can specify multiple plugins: `mise plugins install node ruby python` * `[GIT_URL]` – The git url of the plugin * `[REST]...` – + + #### Flags * `-f,--force` – Reinstall even if plugin exists @@ -390,23 +749,63 @@ Can specify multiple plugins: `mise plugins install node ruby python` This will only install plugins that have matching shorthands. i.e.: they don't need the full git repo url * `-v,--verbose` – Show installation output +Install a plugin + +note that mise automatically can install plugins when you install a tool +e.g.: `mise install node@20` will autoinstall the node plugin + +This behavior can be modified in ~/.config/mise/config.toml +Examples: + # install the node via shorthand + $ mise plugins install node + + # install the node plugin using a specific git url + $ mise plugins install node https://github.com/mise-plugins/rtx-nodejs.git + + # install the node plugin using the git url only + # (node is inferred from the url) + $ mise plugins install https://github.com/mise-plugins/rtx-nodejs.git + + # install the node plugin using a specific ref + $ mise plugins install node https://github.com/mise-plugins/rtx-nodejs.git#v1.0.0 + ### `plugins link` +#### Aliases + +* `ln` #### Args * `` – The name of the plugin e.g.: node, ruby * `[PATH]` – The local path to the plugin e.g.: ./mise-node + + #### Flags * `-f,--force` – Overwrite existing plugin +Symlinks a plugin into mise + +This is used for developing a plugin. +Examples: + # essentially just `ln -s ./mise-node ~/.local/share/mise/plugins/node` + $ mise plugins link node ./mise-node + + # infer plugin name as "node" + $ mise plugins link ./mise-node + ### `plugins ls` +#### Aliases + +* `list` + + #### Flags * `-a,--all` – List all available remote plugins @@ -421,36 +820,85 @@ to show core and user plugins e.g.: https://github.com/asdf-vm/asdf-node.git * `--refs` – Show the git refs for each plugin e.g.: main 1234abc +List installed plugins + +Can also show remotely available plugins to install. +Examples: + $ mise plugins ls + node + ruby + + $ mise plugins ls --urls + node https://github.com/asdf-vm/asdf-node.git + ruby https://github.com/asdf-vm/asdf-ruby.git + ### `plugins ls-remote` +#### Aliases + +* `list-remote` +* `list-all` + + #### Flags * `-u,--urls` – Show the git url for each plugin e.g.: https://github.com/mise-plugins/rtx-nodejs.git * `--only-names` – Only show the name of each plugin by default it will show a "*" next to installed plugins +List all available remote plugins + +The full list is here: https://github.com/jdx/mise/blob/main/src/default_shorthands.rs + +Examples: + $ mise plugins ls-remote + + ### `plugins uninstall` +#### Aliases + +* `remove` +* `rm` #### Args * `[PLUGIN]...` – Plugin(s) to remove + + #### Flags * `-p,--purge` – Also remove the plugin's installs, downloads, and cache * `-a,--all` – Remove all plugins +Removes a plugin +Examples: + $ mise uninstall node + ### `plugins update` +#### Aliases + +* `upgrade` #### Args * `[PLUGIN]...` – Plugin(s) to update + + #### Flags * `-j,--jobs ` – Number of jobs to run in parallel Default: 4 +Updates a plugin to the latest version + +note: this updates the plugin itself, not the runtime versions +Examples: + $ mise plugins update # update all plugins + $ mise plugins update node # update only node + $ mise plugins update node#beta # specify a ref + ### `prune` @@ -458,9 +906,22 @@ Default: 4 #### Args * `[PLUGIN]...` – Prune only versions from this plugin(s) + + #### Flags * `-n,--dry-run` – Do not actually delete anything +Delete unused versions of tools + +mise tracks which config files have been used in ~/.local/share/mise/tracked_config_files +Versions which are no longer the latest specified in any of those configs are deleted. +Versions installed only with environment variables (`MISE__VERSION`) will be deleted, +as will versions only referenced on the command line (`mise exec @`). +Examples: + $ mise prune --dry-run + rm -rf ~/.local/share/mise/versions/node/20.0.0 + rm -rf ~/.local/share/mise/versions/node/20.0.1 + ### `reshim` @@ -471,14 +932,41 @@ Default: 4 * `[VERSION]` – +rebuilds the shim farm + +This creates new shims in ~/.local/share/mise/shims for CLIs that have been added. +mise will try to do this automatically for commands like `npm i -g` but there are +other ways to install things (like using yarn or pnpm for node) that mise does +not know about and so it will be necessary to call this explicitly. + +If you think mise should automatically call this for a particular command, please +open an issue on the mise repo. You can also setup a shell function to reshim +automatically (it's really fast so you don't need to worry about overhead): + +npm() { + command npm "$@" + mise reshim +} +Examples: + $ mise reshim + $ ~/.local/share/mise/shims/node -v + v20.0.0 + + + ### `run` +#### Aliases + +* `r` #### Args * `[TASK]` – Task to run Can specify multiple tasks by separating with `:::` e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2 * `[ARGS]...` – Arguments to pass to the task. Use ":::" to separate tasks + + #### Flags * `-C,--cd ` – Change to this directory before executing the command @@ -496,6 +984,48 @@ Configure with `task_output` config or `MISE_TASK_OUTPUT` env var Configure with `jobs` config or `MISE_JOBS` env var * `-r,--raw` – Read/write directly to stdin/stdout/stderr instead of by line Configure with `raw` config or `MISE_RAW` env var +[experimental] Run a task + +This command will run a task, or multiple tasks in parallel. +Tasks may have dependencies on other tasks or on source files. +If source is configured on a task, it will only run if the source +files have changed. + +Tasks can be defined in .mise.toml or as standalone scripts. +In .mise.toml, tasks take this form: + + [tasks.build] + run = "npm run build" + sources = ["src/**/*.ts"] + outputs = ["dist/**/*.js"] + +Alternatively, tasks can be defined as standalone scripts. +These must be located in the `.mise/tasks` directory. +The name of the script will be the name of the task. + + $ cat .mise/tasks/build<` – The TOML file to update @@ -525,12 +1063,28 @@ Defaults to MISE_DEFAULT_CONFIG_FILENAME environment variable, or ".mise.toml". * `--remove ` – Remove the environment variable from config file Can be used multiple times. +Manage environment variables + +By default this command modifies ".mise.toml" in the current directory. +Examples: + $ mise set NODE_ENV=production + + $ mise set NODE_ENV + production + + $ mise set + key value source + NODE_ENV production ~/.config/mise/config.toml + ### `settings` +Manage settings + + ### `settings get` #### Args @@ -538,64 +1092,187 @@ Can be used multiple times. * `` – The setting to show +Show a current setting + +This is the contents of a single entry in ~/.config/mise/config.toml + +Note that aliases are also stored in this file +but managed separately with `mise aliases get` +Examples: + $ mise settings get legacy_version_file + true + + + ### `settings ls` +#### Aliases + +* `list` + + +Show current settings + +This is the contents of ~/.config/mise/config.toml + +Note that aliases are also stored in this file +but managed separately with `mise aliases` +Examples: + $ mise settings + legacy_version_file = false + ### `settings set` +#### Aliases + +* `add` +* `create` #### Args * `` – The setting to set * `` – The value to set +Add/update a setting + +This modifies the contents of ~/.config/mise/config.toml +Examples: + $ mise settings set legacy_version_file true + + + ### `settings unset` +#### Aliases + +* `rm` +* `remove` +* `delete` +* `del` #### Args * `` – The setting to remove +Clears a setting + +This modifies the contents of ~/.config/mise/config.toml +Examples: + $ mise settings unset legacy_version_file + + + ### `shell` +#### Aliases + +* `sh` #### Args * `[TOOL@VERSION]...` – Tool(s) to use + + #### Flags * `-j,--jobs ` – Number of jobs to run in parallel [default: 4] * `--raw` – Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 * `-u,--unset` – Removes a previously set version +Sets a tool version for the current shell session + +Only works in a session where mise is already activated. +Examples: + $ mise shell node@20 + $ node -v + v20.0.0 + ### `sync` +Add tool versions from external tools to mise + + ### `sync node` + + #### Flags * `--brew` – Get tool versions from Homebrew * `--nvm` – Get tool versions from nvm * `--nodenv` – Get tool versions from nodenv +Symlinks all tool versions from an external tool into mise + +For example, use this to import all Homebrew node installs into mise +Examples: + $ brew install node@18 node@20 + $ mise sync node --brew + $ mise use -g node@18 - uses Homebrew-provided node + ### `sync python` + + #### Flags * `--pyenv` – Get tool versions from pyenv +Symlinks all tool versions from an external tool into mise + +For example, use this to import all pyenv installs into mise +Examples: + $ pyenv install 3.11.0 + $ mise sync python --pyenv + $ mise use -g python@3.11.0 - uses pyenv-provided python + ### `task` +#### Aliases + +* `t` + + #### Flags * `--no-header` – Do not print table header * `--hidden` – Show hidden tasks +[experimental] Manage tasks +Examples: + $ mise task ls + + + +### `task deps` + +#### Args + +* `[TASKS]...` – Tasks to show dependencies for +Can specify multiple tasks by separating with spaces +e.g.: mise task deps lint test check + + +#### Flags + +* `--dot` – Display dependencies in DOT format +[experimental] Display a tree visualization of a dependency graph +Examples: + $ mise task deps + Shows dependencies for all tasks + + $ mise task deps lint test check + Shows dependencies for the "lint", "test" and "check" tasks + + $ mise task deps --dot + Shows dependencies in DOT format + ### `task edit` @@ -603,27 +1280,53 @@ Can be used multiple times. #### Args * `` – Task to edit + + #### Flags * `-p,--path` – Display the path to the task instead of editing it +[experimental] Edit a task with $EDITOR + +The task will be created as a standalone script if it does not already exist. +Examples: + $ mise task edit build + $ mise task edit test + ### `task ls` + + #### Flags * `--no-header` – Do not print table header * `--hidden` – Show hidden tasks +[experimental] List available tasks to execute +These may be included from the config file or from the project's .mise/tasks directory +mise will merge all tasks from all parent directories into this list. + +So if you have global tasks in ~/.config/mise/tasks/* and project-specific tasks in +~/myproject/.mise/tasks/*, then they'll both be available but the project-specific +tasks will override the global ones if they have the same name. +Examples: + $ mise task ls + ### `task run` +#### Aliases + +* `r` #### Args * `[TASK]` – Task to run Can specify multiple tasks by separating with `:::` e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2 * `[ARGS]...` – Arguments to pass to the task. Use ":::" to separate tasks + + #### Flags * `-C,--cd ` – Change to this directory before executing the command @@ -641,6 +1344,48 @@ Configure with `task_output` config or `MISE_TASK_OUTPUT` env var Configure with `jobs` config or `MISE_JOBS` env var * `-r,--raw` – Read/write directly to stdin/stdout/stderr instead of by line Configure with `raw` config or `MISE_RAW` env var +[experimental] Run a task + +This command will run a task, or multiple tasks in parallel. +Tasks may have dependencies on other tasks or on source files. +If source is configured on a task, it will only run if the source +files have changed. + +Tasks can be defined in .mise.toml or as standalone scripts. +In .mise.toml, tasks take this form: + + [tasks.build] + run = "npm run build" + sources = ["src/**/*.ts"] + outputs = ["dist/**/*.js"] + +Alternatively, tasks can be defined as standalone scripts. +These must be located in the `.mise/tasks` directory. +The name of the script will be the name of the task. + + $ cat .mise/tasks/build<` – Specify a file to use instead of ".mise.toml" * `-g,--global` – Use the global config file +Remove environment variable(s) from the config file + +By default this command modifies ".mise.toml" in the current directory. ### `upgrade` +#### Aliases + +* `up` #### Args * `[TOOL@VERSION]...` – Tool(s) to upgrade e.g.: node@20 python@3.10 If not specified, all current tools will be upgraded + + #### Flags * `-n,--dry-run` – Just print what would be done, don't actually do it @@ -691,19 +1476,28 @@ If not specified, all current tools will be upgraded [default: 4] * `-i,--interactive` – Display multiselect menu to choose which tools to upgrade * `--raw` – Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1 +Upgrades outdated tool versions ### `usage` +Generate usage spec + + ### `use` +#### Aliases + +* `u` #### Args * `[TOOL@VERSION]...` – Tool(s) to add to config file e.g.: node@20, cargo:ripgrep@latest npm:prettier@3 If no version is specified, it will default to @latest + + #### Flags * `-f,--force` – Force reinstall even if already installed @@ -720,22 +1514,64 @@ this is the default behavior unless MISE_ASDF_COMPAT=1 * `--pin` – Save exact version to config file e.g.: `mise use --pin node@20` will save 20.0.0 as the version Set MISE_ASDF_COMPAT=1 to make this the default behavior +Change the active version of a tool locally or globally. + +This will install the tool if it is not already installed. +By default, this will use an `.mise.toml` file in the current directory. +Use the --global flag to use the global config file instead. +This replaces asdf's `local` and `global` commands, however those are still available in mise. +Examples: + # set the current version of node to 20.x in .mise.toml of current directory + # will write the fuzzy version (e.g.: 20) + $ mise use node@20 + + # set the current version of node to 20.x in ~/.config/mise/config.toml + # will write the precise version (e.g.: 20.0.0) + $ mise use -g --pin node@20 + + # sets .mise.local.toml (which is intended not to be committed to a project) + $ mise use --env local node@20 + + # sets .mise.staging.toml (which is used if MISE_ENV=staging) + $ mise use --env staging node@20 + ### `version` +Show mise version + + ### `watch` +#### Aliases + +* `w` #### Args * `[ARGS]...` – Extra arguments + + #### Flags * `-t,--task ` – Task to run * `-g,--glob ` – Files to watch Defaults to sources from the task(s) +[experimental] Run a task watching for changes +Examples: + $ mise watch -t build + Runs the "build" task. Will re-run the task when any of its sources change. + Uses "sources" from the task definition to determine which files to watch. + + $ mise watch -t build --glob src/**/*.rs + Runs the "build" task but specify the files to watch with a glob pattern. + This overrides the "sources" from the task definition. + + $ mise run -t build --clear + Extra arguments are passed to watchexec. See `watchexec --help` for details. + ### `where` @@ -752,16 +1588,43 @@ same as the first argument after the "@" used for asdf compatibility +Display the installation path for a runtime + +Must be installed. +Examples: + # Show the latest installed version of node + # If it is is not installed, errors + $ mise where node@20 + /home/jdx/.local/share/mise/installs/node/20.0.0 + + # Show the current, active install directory of node + # Errors if node is not referenced in any .tool-version file + $ mise where node + /home/jdx/.local/share/mise/installs/node/20.0.0 + + + ### `which` #### Args * `` – The bin name to look up + + #### Flags * `--plugin` – Show the plugin name instead of the path * `--version` – Show the version instead of the path * `-t,--tool ` – Use a specific tool@version e.g.: `mise which npm --tool=node@20` +Shows the path that a bin name points to +Examples: + $ mise which node + /home/username/.local/share/mise/installs/node/20.0.0/bin/node + $ mise which node --plugin + node + $ mise which node --version + 20.0.0 + diff --git a/examples/mise.gen.usage.kdl b/examples/mise.gen.usage.kdl index b1a8e4e..5206643 100644 --- a/examples/mise.gen.usage.kdl +++ b/examples/mise.gen.usage.kdl @@ -1,4 +1,5 @@ name "mise" +bin "mise" flag "-C,--cd" help="Change directory before running command" global=true { arg "" } @@ -10,7 +11,7 @@ flag "-q,--quiet" help="Suppress non-error messages" global=true flag "--trace" help="Sets log level to trace" hide=true global=true flag "-v,--verbose" help="Show extra output (use -vv for even more)" var=true global=true count=true flag "-y,--yes" help="Answer yes to all confirmation prompts" global=true -cmd "activate" { +cmd "activate" help="Initializes mise in the current shell session" long_help="Initializes mise in the current shell session\n\nThis should go into your shell's rc file.\nOtherwise, it will only take effect in the current session.\n(e.g. ~/.zshrc, ~/.bashrc)\n\nThis is only intended to be used in interactive sessions, not scripts.\nmise is only capable of updating PATH when the prompt is displayed to the user.\nFor non-interactive use-cases, use shims instead.\n\nTypically this can be added with something like the following:\n\n echo 'eval \"$(mise activate)\"' >> ~/.zshrc\n\nHowever, this requires that \"mise\" is in your PATH. If it is not, you need to\nspecify the full path like this:\n\n echo 'eval \"$(/path/to/mise activate)\"' >> ~/.zshrc" after_long_help="Examples:\n $ eval \"$(mise activate bash)\"\n $ eval \"$(mise activate zsh)\"\n $ mise activate fish | source\n $ execx($(mise activate xonsh))\n" { flag "-s,--shell" help="Shell type to generate the script for" hide=true { arg "" } @@ -18,76 +19,76 @@ cmd "activate" { flag "-q,--quiet" help="Suppress non-error messages" arg "[SHELL_TYPE]" help="Shell type to generate the script for" } -cmd "alias" { +cmd "alias" help="Manage aliases" { alias "a" alias "aliases" hide=true flag "-p,--plugin" help="filter aliases by plugin" { arg "" } flag "--no-header" help="Don't show table header" - cmd "get" { + cmd "get" help="Show an alias for a plugin" long_help="Show an alias for a plugin\n\nThis is the contents of an alias. entry in ~/.config/mise/config.toml" after_long_help="Examples:\n $ mise alias get node lts-hydrogen\n 20.0.0\n" { arg "" help="The plugin to show the alias for" arg "" help="The alias to show" } - cmd "ls" { + cmd "ls" help="List aliases\nShows the aliases that can be specified.\nThese can come from user config or from plugins in `bin/list-aliases`." long_help="List aliases\nShows the aliases that can be specified.\nThese can come from user config or from plugins in `bin/list-aliases`.\n\nFor user config, aliases are defined like the following in `~/.config/mise/config.toml`:\n\n [alias.node]\n lts = \"20.0.0\"" after_long_help="Examples:\n $ mise aliases\n node lts-hydrogen 20.0.0\n" { alias "list" flag "--no-header" help="Don't show table header" arg "[PLUGIN]" help="Show aliases for " } - cmd "set" { + cmd "set" help="Add/update an alias for a plugin" long_help="Add/update an alias for a plugin\n\nThis modifies the contents of ~/.config/mise/config.toml" after_long_help="Examples:\n $ mise alias set node lts-hydrogen 18.0.0\n" { alias "add" "create" arg "" help="The plugin to set the alias for" arg "" help="The alias to set" arg "" help="The value to set the alias to" } - cmd "unset" { + cmd "unset" help="Clears an alias for a plugin" long_help="Clears an alias for a plugin\n\nThis modifies the contents of ~/.config/mise/config.toml" after_long_help="Examples:\n $ mise alias unset node lts-hydrogen\n" { alias "rm" "remove" "delete" "del" arg "" help="The plugin to remove the alias from" arg "" help="The alias to remove" } } -cmd "asdf" hide=true { +cmd "asdf" hide=true help="[internal] simulates asdf for plugins that call \"asdf\" internally" { arg "[ARGS]..." help="all arguments" var=true } -cmd "bin-paths" -cmd "cache" { - cmd "clear" { +cmd "bin-paths" help="List all the active runtime bin paths" +cmd "cache" help="Manage the mise cache" long_help="Manage the mise cache\n\nRun `mise cache` with no args to view the current cache directory." { + cmd "clear" help="Deletes all cache files in mise" { alias "c" alias "clean" hide=true arg "[PLUGIN]..." help="Plugin(s) to clear cache for e.g.: node, python" var=true } } -cmd "completion" { +cmd "completion" help="Generate shell completions" after_long_help="Examples:\n $ mise completion bash > /etc/bash_completion.d/mise\n $ mise completion zsh > /usr/local/share/zsh/site-functions/_mise\n $ mise completion fish > ~/.config/fish/completions/mise.fish\n" { alias "complete" "completions" hide=true flag "-s,--shell" help="Shell type to generate completions for" hide=true { arg "" } arg "[SHELL]" help="Shell type to generate completions for" } -cmd "config" { +cmd "config" help="[experimental] Manage config files" { alias "cfg" flag "--no-header" help="Do not print table header" - cmd "ls" { + cmd "ls" help="[experimental] List config files currently in use" after_long_help="Examples:\n $ mise config ls\n" { flag "--no-header" help="Do not print table header" } - cmd "generate" { + cmd "generate" help="[experimental] Generate an .mise.toml file" after_long_help="Examples:\n $ mise cf generate > .mise.toml\n $ mise cf generate --output=.mise.toml\n" { alias "g" flag "-o,--output" help="Output to file instead of stdout" { arg "" } } } -cmd "current" { +cmd "current" help="Shows current active and installed runtime versions" long_help="Shows current active and installed runtime versions\n\nThis is similar to `mise ls --current`, but this only shows the runtime\nand/or version. It's designed to fit into scripts more easily." after_long_help="Examples:\n # outputs `.tool-versions` compatible format\n $ mise current\n python 3.11.0 3.10.0\n shfmt 3.6.0\n shellcheck 0.9.0\n node 20.0.0\n \n $ mise current node\n 20.0.0\n \n # can output multiple versions\n $ mise current python\n 3.11.0 3.10.0\n" { arg "[PLUGIN]" help="Plugin to show versions of e.g.: ruby, node, cargo:eza, npm:prettier, etc" } -cmd "deactivate" -cmd "direnv" { - cmd "envrc" hide=true - cmd "exec" hide=true - cmd "activate" +cmd "deactivate" help="Disable mise for current shell session" long_help="Disable mise for current shell session\n\nThis can be used to temporarily disable mise in a shell session." after_long_help="Examples:\n $ mise deactivate bash\n $ mise deactivate zsh\n $ mise deactivate fish\n $ execx($(mise deactivate xonsh))\n" +cmd "direnv" help="Output direnv function to use mise inside direnv" long_help="Output direnv function to use mise inside direnv\n\nSee https://mise.rtx.dev/direnv.html for more information\n\nBecause this generates the legacy files based on currently installed plugins,\nyou should run this command after installing new plugins. Otherwise\ndirenv may not know to update environment variables when legacy file versions change." { + cmd "envrc" hide=true help="[internal] This is an internal command that writes an envrc file\nfor direnv to consume." + cmd "exec" hide=true help="[internal] This is an internal command that writes an envrc file\nfor direnv to consume." + cmd "activate" help="Output direnv function to use mise inside direnv" long_help="Output direnv function to use mise inside direnv\n\nSee https://mise.jdx.dev/direnv.html for more information\n\nBecause this generates the legacy files based on currently installed plugins,\nyou should run this command after installing new plugins. Otherwise\ndirenv may not know to update environment variables when legacy file versions change." after_long_help="Examples:\n $ mise direnv activate > ~/.config/direnv/lib/use_mise.sh\n $ echo 'use mise' > .envrc\n $ direnv allow\n" } -cmd "doctor" -cmd "env" { +cmd "doctor" help="Check mise installation for possible problems." after_long_help="Examples:\n $ mise doctor\n [WARN] plugin node is not installed\n" +cmd "env" help="Exports env vars to activate mise a single time" long_help="Exports env vars to activate mise a single time\n\nUse this if you don't want to permanently install mise. It's not necessary to\nuse this if you have `mise activate` in your shell rc file." after_long_help="Examples:\n $ eval \"$(mise env -s bash)\"\n $ eval \"$(mise env -s zsh)\"\n $ mise env -s fish | source\n $ execx($(mise env -s xonsh))\n" { alias "e" flag "-s,--shell" help="Shell type to generate environment variables for" { arg "" @@ -95,7 +96,7 @@ cmd "env" { flag "-J,--json" help="Output in JSON format" arg "[TOOL@VERSION]..." help="Tool(s) to use" var=true } -cmd "exec" { +cmd "exec" help="Execute a command with tool(s) set" long_help="Execute a command with tool(s) set\n\nuse this to avoid modifying the shell session or running ad-hoc commands with mise tools set.\n\nTools will be loaded from .mise.toml/.tool-versions, though they can be overridden with args\nNote that only the plugin specified will be overridden, so if a `.tool-versions` file\nincludes \"node 20\" but you run `mise exec python@3.11`; it will still load node@20.\n\nThe \"--\" separates runtimes from the commands to pass along to the subprocess." after_long_help="Examples:\n $ mise exec node@20 -- node ./app.js # launch app.js using node-20.x\n $ mise x node@20 -- node ./app.js # shorter alias\n\n # Specify command as a string:\n $ mise exec node@20 python@3.11 --command \"node -v && python -V\"\n\n # Run a command in a different directory:\n $ mise x -C /path/to/project node@20 -- node ./app.js\n" { alias "x" flag "-c,--command" help="Command string to execute" { arg "" @@ -107,7 +108,7 @@ cmd "exec" { arg "[TOOL@VERSION]..." help="Tool(s) to start e.g.: node@20 python@3.10" var=true arg "[COMMAND]..." help="Command string to execute (same as --command)" var=true } -cmd "global" hide=true { +cmd "global" hide=true help="Sets/gets the global tool version(s)" long_help="Sets/gets the global tool version(s)\n\nDisplays the contents of ~/.tool-versions after writing.\nThe file is `$HOME/.config/mise/config.toml` by default. It can be changed with `$MISE_GLOBAL_CONFIG_FILE`.\nIf `$MISE_GLOBAL_CONFIG_FILE` is set to anything that ends in `.toml`, it will be parsed as `.mise.toml`.\nOtherwise, it will be parsed as a `.tool-versions` file.\n\nUse `mise local` to set a tool version locally in the current directory." after_long_help="Examples:\n # set the current version of node to 20.x\n # will use a fuzzy version (e.g.: 20) in .tool-versions file\n $ mise global --fuzzy node@20\n\n # set the current version of node to 20.x\n # will use a precise version (e.g.: 20.0.0) in .tool-versions file\n $ mise global --pin node@20\n\n # show the current version of node in ~/.tool-versions\n $ mise global node\n 20.0.0\n" { alias "g" hide=true flag "--pin" help="Save exact version to `~/.tool-versions`\ne.g.: `mise global --pin node@20` will save `node 20.0.0` to ~/.tool-versions" flag "--fuzzy" help="Save fuzzy version to `~/.tool-versions`\ne.g.: `mise global --fuzzy node@20` will save `node 20` to ~/.tool-versions\nthis is the default behavior unless MISE_ASDF_COMPAT=1" @@ -117,24 +118,24 @@ cmd "global" hide=true { flag "--path" help="Get the path of the global config file" arg "[TOOL@VERSION]..." help="Tool(s) to add to .tool-versions\ne.g.: node@20\nIf this is a single tool with no version, the current value of the global\n.tool-versions will be displayed" var=true } -cmd "hook-env" hide=true { +cmd "hook-env" hide=true help="[internal] called by activate hook to update env vars directory change" { flag "-s,--shell" help="Shell type to generate script for" { arg "" } flag "--status" help="Show \"mise: @\" message when changing directories" flag "-q,--quiet" help="Hide warnings such as when a tool is not installed" } -cmd "hook-not-found" hide=true { +cmd "hook-not-found" hide=true help="[internal] called by shell when a command is not found" { flag "-s,--shell" help="Shell type to generate script for" { arg "" } arg "" help="Attempted bin to run" } -cmd "implode" { +cmd "implode" help="Removes mise CLI and all related data" long_help="Removes mise CLI and all related data\n\nSkips config directory by default." { flag "--config" help="Also remove config directory" flag "-n,--dry-run" help="List directories that would be removed without actually removing them" } -cmd "install" { +cmd "install" help="Install a tool version" long_help="Install a tool version\n\nThis will install a tool version to `~/.local/share/mise/installs//`\nIt won't be used simply by being installed, however.\nFor that, you must set up a `.mise.toml`/`.tool-version` file manually or with `mise use`.\nOr you can call a tool version explicitly with `mise exec @ -- `.\n\nTools will be installed in parallel. To disable, set `--jobs=1` or `MISE_JOBS=1`" after_long_help="Examples:\n $ mise install node@20.0.0 # install specific node version\n $ mise install node@20 # install fuzzy node version\n $ mise install node # install version specified in .tool-versions or .mise.toml\n $ mise install # installs everything specified in .tool-versions or .mise.toml\n" { alias "i" flag "-f,--force" help="Force reinstall even if already installed" flag "-j,--jobs" help="Number of jobs to run in parallel\n[default: 4]" { @@ -144,18 +145,18 @@ cmd "install" { flag "-v,--verbose" help="Show installation output" var=true count=true arg "[TOOL@VERSION]..." help="Tool(s) to install e.g.: node@20" var=true } -cmd "latest" { +cmd "latest" help="Gets the latest available version for a plugin" after_long_help="Examples:\n $ mise latest node@20 # get the latest version of node 20\n 20.0.0\n\n $ mise latest node # get the latest stable version of node\n 20.0.0\n" { flag "-i,--installed" help="Show latest installed instead of available version" arg "" help="Tool to get the latest version of" arg "[ASDF_VERSION]" help="The version prefix to use when querying the latest version same as the first argument after the \"@\" used for asdf compatibility" hide=true } -cmd "link" { +cmd "link" help="Symlinks a tool version into mise" long_help="Symlinks a tool version into mise\n\nUse this for adding installs either custom compiled outside\nmise or built with a different tool." after_long_help="Examples:\n # build node-20.0.0 with node-build and link it into mise\n $ node-build 20.0.0 ~/.nodes/20.0.0\n $ mise link node@20.0.0 ~/.nodes/20.0.0\n\n # have mise use the python version provided by Homebrew\n $ brew install node\n $ mise link node@brew $(brew --prefix node)\n $ mise use node@brew\n" { alias "ln" flag "-f,--force" help="Overwrite an existing tool version if it exists" arg "" help="Tool name and version to create a symlink for" arg "" help="The local path to the tool version\ne.g.: ~/.nvm/versions/node/v20.0.0" } -cmd "local" hide=true { +cmd "local" hide=true help="Sets/gets tool version in local .tool-versions or .mise.toml" long_help="Sets/gets tool version in local .tool-versions or .mise.toml\n\nUse this to set a tool's version when within a directory\nUse `mise global` to set a tool version globally\nThis uses `.tool-version` by default unless there is a `.mise.toml` file or if `MISE_USE_TOML`\nis set. A future v2 release of mise will default to using `.mise.toml`." after_long_help="Examples:\n # set the current version of node to 20.x for the current directory\n # will use a precise version (e.g.: 20.0.0) in .tool-versions file\n $ mise local node@20\n\n # set node to 20.x for the current project (recurses up to find .tool-versions)\n $ mise local -p node@20\n\n # set the current version of node to 20.x for the current directory\n # will use a fuzzy version (e.g.: 20) in .tool-versions file\n $ mise local --fuzzy node@20\n\n # removes node from .tool-versions\n $ mise local --remove=node\n\n # show the current version of node in .tool-versions\n $ mise local node\n 20.0.0\n" { alias "l" hide=true flag "-p,--parent" help="Recurse up to find a .tool-versions file rather than using the current directory only\nby default this command will only set the tool in the current directory (\"$PWD/.tool-versions\")" flag "--pin" help="Save exact version to `.tool-versions`\ne.g.: `mise local --pin node@20` will save `node 20.0.0` to .tool-versions" @@ -166,7 +167,7 @@ cmd "local" hide=true { flag "--path" help="Get the path of the config file" arg "[TOOL@VERSION]..." help="Tool(s) to add to .tool-versions/.mise.toml\ne.g.: node@20\nif this is a single tool with no version,\nthe current value of .tool-versions/.mise.toml will be displayed" var=true } -cmd "ls" { +cmd "ls" help="List installed and/or currently selected tool versions" after_long_help="Examples:\n $ mise ls\n node 20.0.0 ~/src/myapp/.tool-versions latest\n python 3.11.0 ~/.tool-versions 3.10\n python 3.10.0\n\n $ mise ls --current\n node 20.0.0 ~/src/myapp/.tool-versions 20\n python 3.11.0 ~/.tool-versions 3.11.0\n\n $ mise ls --json\n {\n \"node\": [\n {\n \"version\": \"20.0.0\",\n \"install_path\": \"/Users/jdx/.mise/installs/node/20.0.0\",\n \"source\": {\n \"type\": \".mise.toml\",\n \"path\": \"/Users/jdx/.mise.toml\"\n }\n }\n ],\n \"python\": [...]\n }\n" { alias "list" flag "-p,--plugin" hide=true { arg "" @@ -183,16 +184,16 @@ cmd "ls" { flag "--no-header" help="Don't display headers" arg "[PLUGIN]..." help="Only show tool versions from [PLUGIN]" var=true } -cmd "ls-remote" { +cmd "ls-remote" help="List runtime versions available for install" long_help="List runtime versions available for install\n\nnote that the results are cached for 24 hours\nrun `mise cache clean` to clear the cache and get fresh results" after_long_help="Examples:\n $ mise ls-remote node\n 18.0.0\n 20.0.0\n\n $ mise ls-remote node@20\n 20.0.0\n 20.1.0\n\n $ mise ls-remote node 20\n 20.0.0\n 20.1.0\n" { alias "list-all" "list-remote" hide=true flag "--all" help="Show all installed plugins and versions" arg "[TOOL@VERSION]" help="Plugin to get versions for" arg "[PREFIX]" help="The version prefix to use when querying the latest version\nsame as the first argument after the \"@\"" } -cmd "outdated" { +cmd "outdated" help="Shows outdated tool versions" after_long_help="Examples:\n $ mise outdated\n Plugin Requested Current Latest\n python 3.11 3.11.0 3.11.1\n node 20 20.0.0 20.1.0\n\n $ mise outdated node\n Plugin Requested Current Latest\n node 20 20.0.0 20.1.0\n" { arg "[TOOL@VERSION]..." help="Tool(s) to show outdated versions for\ne.g.: node@20 python@3.10\nIf not specified, all tools in global and local configs will be shown" var=true } -cmd "plugins" { +cmd "plugins" help="Manage plugins" { alias "p" alias "plugin" "plugin-list" hide=true flag "-a,--all" help="list all available remote plugins" long_help="list all available remote plugins\n\nsame as `mise plugins ls-remote`" hide=true @@ -200,7 +201,7 @@ cmd "plugins" { flag "--user" help="List installed plugins" long_help="List installed plugins\n\nThis is the default behavior but can be used with --core\nto show core and user plugins" flag "-u,--urls" help="Show the git url for each plugin\ne.g.: https://github.com/asdf-vm/asdf-node.git" flag "--refs" help="Show the git refs for each plugin\ne.g.: main 1234abc" hide=true - cmd "install" { + cmd "install" help="Install a plugin" long_help="Install a plugin\n\nnote that mise automatically can install plugins when you install a tool\ne.g.: `mise install node@20` will autoinstall the node plugin\n\nThis behavior can be modified in ~/.config/mise/config.toml" after_long_help="Examples:\n # install the node via shorthand\n $ mise plugins install node\n\n # install the node plugin using a specific git url\n $ mise plugins install node https://github.com/mise-plugins/rtx-nodejs.git\n\n # install the node plugin using the git url only\n # (node is inferred from the url)\n $ mise plugins install https://github.com/mise-plugins/rtx-nodejs.git\n\n # install the node plugin using a specific ref\n $ mise plugins install node https://github.com/mise-plugins/rtx-nodejs.git#v1.0.0\n" { alias "i" "a" "add" flag "-f,--force" help="Reinstall even if plugin exists" flag "-a,--all" help="Install all missing plugins\nThis will only install plugins that have matching shorthands.\ni.e.: they don't need the full git repo url" @@ -209,13 +210,13 @@ cmd "plugins" { arg "[GIT_URL]" help="The git url of the plugin" arg "[REST]..." var=true hide=true } - cmd "link" { + cmd "link" help="Symlinks a plugin into mise" long_help="Symlinks a plugin into mise\n\nThis is used for developing a plugin." after_long_help="Examples:\n # essentially just `ln -s ./mise-node ~/.local/share/mise/plugins/node`\n $ mise plugins link node ./mise-node\n\n # infer plugin name as \"node\"\n $ mise plugins link ./mise-node\n" { alias "ln" flag "-f,--force" help="Overwrite existing plugin" arg "" help="The name of the plugin\ne.g.: node, ruby" arg "[PATH]" help="The local path to the plugin\ne.g.: ./mise-node" } - cmd "ls" { + cmd "ls" help="List installed plugins" long_help="List installed plugins\n\nCan also show remotely available plugins to install." after_long_help="Examples:\n $ mise plugins ls\n node\n ruby\n\n $ mise plugins ls --urls\n node https://github.com/asdf-vm/asdf-node.git\n ruby https://github.com/asdf-vm/asdf-ruby.git\n" { alias "list" flag "-a,--all" help="List all available remote plugins\nSame as `mise plugins ls-remote`" hide=true flag "-c,--core" help="The built-in plugins only\nNormally these are not shown" @@ -223,18 +224,18 @@ cmd "plugins" { flag "-u,--urls" help="Show the git url for each plugin\ne.g.: https://github.com/asdf-vm/asdf-node.git" flag "--refs" help="Show the git refs for each plugin\ne.g.: main 1234abc" hide=true } - cmd "ls-remote" { + cmd "ls-remote" help="List all available remote plugins" long_help="\nList all available remote plugins\n\nThe full list is here: https://github.com/jdx/mise/blob/main/src/default_shorthands.rs\n\nExamples:\n $ mise plugins ls-remote\n" { alias "list-remote" "list-all" flag "-u,--urls" help="Show the git url for each plugin e.g.: https://github.com/mise-plugins/rtx-nodejs.git" flag "--only-names" help="Only show the name of each plugin by default it will show a \"*\" next to installed plugins" } - cmd "uninstall" { + cmd "uninstall" help="Removes a plugin" after_long_help="Examples:\n $ mise uninstall node\n" { alias "remove" "rm" flag "-p,--purge" help="Also remove the plugin's installs, downloads, and cache" flag "-a,--all" help="Remove all plugins" arg "[PLUGIN]..." help="Plugin(s) to remove" var=true } - cmd "update" { + cmd "update" help="Updates a plugin to the latest version" long_help="Updates a plugin to the latest version\n\nnote: this updates the plugin itself, not the runtime versions" after_long_help="Examples:\n $ mise plugins update # update all plugins\n $ mise plugins update node # update only node\n $ mise plugins update node#beta # specify a ref\n" { alias "upgrade" flag "-j,--jobs" help="Number of jobs to run in parallel\nDefault: 4" { arg "" @@ -242,15 +243,15 @@ cmd "plugins" { arg "[PLUGIN]..." help="Plugin(s) to update" var=true } } -cmd "prune" { +cmd "prune" help="Delete unused versions of tools" long_help="Delete unused versions of tools\n\nmise tracks which config files have been used in ~/.local/share/mise/tracked_config_files\nVersions which are no longer the latest specified in any of those configs are deleted.\nVersions installed only with environment variables (`MISE__VERSION`) will be deleted,\nas will versions only referenced on the command line (`mise exec @`)." after_long_help="Examples:\n $ mise prune --dry-run\n rm -rf ~/.local/share/mise/versions/node/20.0.0\n rm -rf ~/.local/share/mise/versions/node/20.0.1\n" { flag "-n,--dry-run" help="Do not actually delete anything" arg "[PLUGIN]..." help="Prune only versions from this plugin(s)" var=true } -cmd "reshim" { +cmd "reshim" help="rebuilds the shim farm" long_help="rebuilds the shim farm\n\nThis creates new shims in ~/.local/share/mise/shims for CLIs that have been added.\nmise will try to do this automatically for commands like `npm i -g` but there are\nother ways to install things (like using yarn or pnpm for node) that mise does\nnot know about and so it will be necessary to call this explicitly.\n\nIf you think mise should automatically call this for a particular command, please\nopen an issue on the mise repo. You can also setup a shell function to reshim\nautomatically (it's really fast so you don't need to worry about overhead):\n\nnpm() {\n command npm \"$@\"\n mise reshim\n}" after_long_help="Examples:\n $ mise reshim\n $ ~/.local/share/mise/shims/node -v\n v20.0.0\n" { arg "[PLUGIN]" hide=true arg "[VERSION]" hide=true } -cmd "run" { +cmd "run" help="[experimental] Run a task" long_help="[experimental] Run a task\n\nThis command will run a task, or multiple tasks in parallel.\nTasks may have dependencies on other tasks or on source files.\nIf source is configured on a task, it will only run if the source\nfiles have changed.\n\nTasks can be defined in .mise.toml or as standalone scripts.\nIn .mise.toml, tasks take this form:\n\n [tasks.build]\n run = \"npm run build\"\n sources = [\"src/**/*.ts\"]\n outputs = [\"dist/**/*.js\"]\n\nAlternatively, tasks can be defined as standalone scripts.\nThese must be located in the `.mise/tasks` directory.\nThe name of the script will be the name of the task.\n\n $ cat .mise/tasks/build<" @@ -269,13 +270,13 @@ cmd "run" { arg "[TASK]" help="Task to run\nCan specify multiple tasks by separating with `:::`\ne.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2" default="default" arg "[ARGS]..." help="Arguments to pass to the task. Use \":::\" to separate tasks" var=true } -cmd "self-update" { +cmd "self-update" help="Updates mise itself" long_help="Updates mise itself\n\nUses the GitHub Releases API to find the latest release and binary\nBy default, this will also update any installed plugins" { flag "-f,--force" help="Update even if already up to date" flag "--no-plugins" help="Disable auto-updating plugins" flag "-y,--yes" help="Skip confirmation prompt" arg "[VERSION]" help="Update to a specific version" } -cmd "set" { +cmd "set" help="Manage environment variables" long_help="Manage environment variables\n\nBy default this command modifies \".mise.toml\" in the current directory." after_long_help="Examples:\n $ mise set NODE_ENV=production\n\n $ mise set NODE_ENV\n production\n\n $ mise set\n key value source\n NODE_ENV production ~/.config/mise/config.toml\n" { alias "ev" "env-vars" hide=true flag "--file" help="The TOML file to update" long_help="The TOML file to update\n\nDefaults to MISE_DEFAULT_CONFIG_FILENAME environment variable, or \".mise.toml\"." { arg "" @@ -286,24 +287,24 @@ cmd "set" { } arg "[ENV_VARS]..." help="Environment variable(s) to set\ne.g.: NODE_ENV=production" var=true } -cmd "settings" { - cmd "get" { +cmd "settings" help="Manage settings" { + cmd "get" help="Show a current setting" long_help="Show a current setting\n\nThis is the contents of a single entry in ~/.config/mise/config.toml\n\nNote that aliases are also stored in this file\nbut managed separately with `mise aliases get`" after_long_help="Examples:\n $ mise settings get legacy_version_file\n true\n" { arg "" help="The setting to show" } - cmd "ls" { + cmd "ls" help="Show current settings" long_help="Show current settings\n\nThis is the contents of ~/.config/mise/config.toml\n\nNote that aliases are also stored in this file\nbut managed separately with `mise aliases`" after_long_help="Examples:\n $ mise settings\n legacy_version_file = false\n" { alias "list" } - cmd "set" { + cmd "set" help="Add/update a setting" long_help="Add/update a setting\n\nThis modifies the contents of ~/.config/mise/config.toml" after_long_help="Examples:\n $ mise settings set legacy_version_file true\n" { alias "add" "create" arg "" help="The setting to set" arg "" help="The value to set" } - cmd "unset" { + cmd "unset" help="Clears a setting" long_help="Clears a setting\n\nThis modifies the contents of ~/.config/mise/config.toml" after_long_help="Examples:\n $ mise settings unset legacy_version_file\n" { alias "rm" "remove" "delete" "del" arg "" help="The setting to remove" } } -cmd "shell" { +cmd "shell" help="Sets a tool version for the current shell session" long_help="Sets a tool version for the current shell session\n\nOnly works in a session where mise is already activated." after_long_help="Examples:\n $ mise shell node@20\n $ node -v\n v20.0.0\n" { alias "sh" flag "-j,--jobs" help="Number of jobs to run in parallel\n[default: 4]" { arg "" @@ -312,30 +313,34 @@ cmd "shell" { flag "-u,--unset" help="Removes a previously set version" arg "[TOOL@VERSION]..." help="Tool(s) to use" var=true } -cmd "sync" subcommand_required=true { - cmd "node" { +cmd "sync" subcommand_required=true help="Add tool versions from external tools to mise" { + cmd "node" help="Symlinks all tool versions from an external tool into mise" long_help="Symlinks all tool versions from an external tool into mise\n\nFor example, use this to import all Homebrew node installs into mise" after_long_help="Examples:\n $ brew install node@18 node@20\n $ mise sync node --brew\n $ mise use -g node@18 - uses Homebrew-provided node\n" { flag "--brew" help="Get tool versions from Homebrew" flag "--nvm" help="Get tool versions from nvm" flag "--nodenv" help="Get tool versions from nodenv" } - cmd "python" { + cmd "python" help="Symlinks all tool versions from an external tool into mise" long_help="Symlinks all tool versions from an external tool into mise\n\nFor example, use this to import all pyenv installs into mise" after_long_help="Examples:\n $ pyenv install 3.11.0\n $ mise sync python --pyenv\n $ mise use -g python@3.11.0 - uses pyenv-provided python\n" { flag "--pyenv" help="Get tool versions from pyenv" required=true } } -cmd "task" { +cmd "task" help="[experimental] Manage tasks" after_long_help="Examples:\n $ mise task ls\n" { alias "t" alias "tasks" hide=true flag "--no-header" help="Do not print table header" flag "--hidden" help="Show hidden tasks" - cmd "edit" { + cmd "deps" help="[experimental] Display a tree visualization of a dependency graph" after_long_help="Examples:\n $ mise task deps\n Shows dependencies for all tasks\n\n $ mise task deps lint test check\n Shows dependencies for the \"lint\", \"test\" and \"check\" tasks\n\n $ mise task deps --dot\n Shows dependencies in DOT format\n" { + flag "--dot" help="Display dependencies in DOT format" + arg "[TASKS]..." help="Tasks to show dependencies for\nCan specify multiple tasks by separating with spaces\ne.g.: mise task deps lint test check" var=true + } + cmd "edit" help="[experimental] Edit a task with $EDITOR" long_help="[experimental] Edit a task with $EDITOR\n\nThe task will be created as a standalone script if it does not already exist." after_long_help="Examples:\n $ mise task edit build\n $ mise task edit test\n" { flag "-p,--path" help="Display the path to the task instead of editing it" arg "" help="Task to edit" } - cmd "ls" { + cmd "ls" help="[experimental] List available tasks to execute\nThese may be included from the config file or from the project's .mise/tasks directory\nmise will merge all tasks from all parent directories into this list." long_help="[experimental] List available tasks to execute\nThese may be included from the config file or from the project's .mise/tasks directory\nmise will merge all tasks from all parent directories into this list.\n\nSo if you have global tasks in ~/.config/mise/tasks/* and project-specific tasks in\n~/myproject/.mise/tasks/*, then they'll both be available but the project-specific\ntasks will override the global ones if they have the same name." after_long_help="Examples:\n $ mise task ls\n" { flag "--no-header" help="Do not print table header" flag "--hidden" help="Show hidden tasks" } - cmd "run" { + cmd "run" help="[experimental] Run a task" long_help="[experimental] Run a task\n\nThis command will run a task, or multiple tasks in parallel.\nTasks may have dependencies on other tasks or on source files.\nIf source is configured on a task, it will only run if the source\nfiles have changed.\n\nTasks can be defined in .mise.toml or as standalone scripts.\nIn .mise.toml, tasks take this form:\n\n [tasks.build]\n run = \"npm run build\"\n sources = [\"src/**/*.ts\"]\n outputs = [\"dist/**/*.js\"]\n\nAlternatively, tasks can be defined as standalone scripts.\nThese must be located in the `.mise/tasks` directory.\nThe name of the script will be the name of the task.\n\n $ cat .mise/tasks/build<" @@ -355,25 +360,25 @@ cmd "task" { arg "[ARGS]..." help="Arguments to pass to the task. Use \":::\" to separate tasks" var=true } } -cmd "trust" { +cmd "trust" help="Marks a config file as trusted" long_help="Marks a config file as trusted\n\nThis means mise will parse the file with potentially dangerous\nfeatures enabled.\n\nThis includes:\n- environment variables\n- templates\n- `path:` plugin versions" after_long_help="Examples:\n # trusts ~/some_dir/.mise.toml\n $ mise trust ~/some_dir/.mise.toml\n\n # trusts .mise.toml in the current or parent directory\n $ mise trust\n" { flag "-a,--all" help="Trust all config files in the current directory and its parents" flag "--untrust" help="No longer trust this config" arg "[CONFIG_FILE]" help="The config file to trust" } -cmd "uninstall" { +cmd "uninstall" help="Removes runtime versions" after_long_help="Examples:\n $ mise uninstall node@18.0.0 # will uninstall specific version\n $ mise uninstall node # will uninstall current node version\n $ mise uninstall --all node@18.0.0 # will uninstall all node versions\n" { alias "remove" "rm" flag "-a,--all" help="Delete all installed versions" flag "-n,--dry-run" help="Do not actually delete anything" arg "[TOOL@VERSION]..." help="Tool(s) to remove" var=true } -cmd "unset" { +cmd "unset" help="Remove environment variable(s) from the config file" long_help="Remove environment variable(s) from the config file\n\nBy default this command modifies \".mise.toml\" in the current directory." { flag "-f,--file" help="Specify a file to use instead of \".mise.toml\"" { arg "" } flag "-g,--global" help="Use the global config file" arg "[KEYS]..." help="Environment variable(s) to remove\ne.g.: NODE_ENV" var=true } -cmd "upgrade" { +cmd "upgrade" help="Upgrades outdated tool versions" { alias "up" flag "-n,--dry-run" help="Just print what would be done, don't actually do it" flag "-j,--jobs" help="Number of jobs to run in parallel\n[default: 4]" { @@ -383,8 +388,8 @@ cmd "upgrade" { flag "--raw" help="Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1" arg "[TOOL@VERSION]..." help="Tool(s) to upgrade\ne.g.: node@20 python@3.10\nIf not specified, all current tools will be upgraded" var=true } -cmd "usage" -cmd "use" { +cmd "usage" help="Generate usage spec" +cmd "use" help="Change the active version of a tool locally or globally." long_help="Change the active version of a tool locally or globally.\n\nThis will install the tool if it is not already installed.\nBy default, this will use an `.mise.toml` file in the current directory.\nUse the --global flag to use the global config file instead.\nThis replaces asdf's `local` and `global` commands, however those are still available in mise." after_long_help="Examples:\n # set the current version of node to 20.x in .mise.toml of current directory\n # will write the fuzzy version (e.g.: 20)\n $ mise use node@20\n\n # set the current version of node to 20.x in ~/.config/mise/config.toml\n # will write the precise version (e.g.: 20.0.0)\n $ mise use -g --pin node@20\n\n # sets .mise.local.toml (which is intended not to be committed to a project)\n $ mise use --env local node@20\n\n # sets .mise.staging.toml (which is used if MISE_ENV=staging)\n $ mise use --env staging node@20\n" { alias "u" flag "-f,--force" help="Force reinstall even if already installed" flag "--fuzzy" help="Save fuzzy version to config file\ne.g.: `mise use --fuzzy node@20` will save 20 as the version\nthis is the default behavior unless MISE_ASDF_COMPAT=1" @@ -405,10 +410,10 @@ cmd "use" { flag "--pin" help="Save exact version to config file\ne.g.: `mise use --pin node@20` will save 20.0.0 as the version\nSet MISE_ASDF_COMPAT=1 to make this the default behavior" arg "[TOOL@VERSION]..." help="Tool(s) to add to config file\ne.g.: node@20, cargo:ripgrep@latest npm:prettier@3\nIf no version is specified, it will default to @latest" var=true } -cmd "version" { +cmd "version" help="Show mise version" { alias "v" hide=true } -cmd "watch" { +cmd "watch" help="[experimental] Run a task watching for changes" after_long_help="Examples:\n $ mise watch -t build\n Runs the \"build\" task. Will re-run the task when any of its sources change.\n Uses \"sources\" from the task definition to determine which files to watch.\n\n $ mise watch -t build --glob src/**/*.rs\n Runs the \"build\" task but specify the files to watch with a glob pattern.\n This overrides the \"sources\" from the task definition.\n\n $ mise run -t build --clear\n Extra arguments are passed to watchexec. See `watchexec --help` for details.\n" { alias "w" flag "-t,--task" help="Task to run" var=true { arg "" @@ -418,11 +423,11 @@ cmd "watch" { } arg "[ARGS]..." help="Extra arguments" var=true } -cmd "where" { +cmd "where" help="Display the installation path for a runtime" long_help="Display the installation path for a runtime\n\nMust be installed." after_long_help="Examples:\n # Show the latest installed version of node\n # If it is is not installed, errors\n $ mise where node@20\n /home/jdx/.local/share/mise/installs/node/20.0.0\n\n # Show the current, active install directory of node\n # Errors if node is not referenced in any .tool-version file\n $ mise where node\n /home/jdx/.local/share/mise/installs/node/20.0.0\n" { arg "" help="Tool(s) to look up\ne.g.: ruby@3\nif \"@\" is specified, it will show the latest installed version\nthat matches the prefix\notherwise, it will show the current, active installed version" arg "[ASDF_VERSION]" help="the version prefix to use when querying the latest version\nsame as the first argument after the \"@\"\nused for asdf compatibility" hide=true } -cmd "which" { +cmd "which" help="Shows the path that a bin name points to" after_long_help="Examples:\n $ mise which node\n /home/username/.local/share/mise/installs/node/20.0.0/bin/node\n $ mise which node --plugin\n node\n $ mise which node --version\n 20.0.0\n" { flag "--plugin" help="Show the plugin name instead of the path" flag "--version" help="Show the version instead of the path" flag "-t,--tool" help="Use a specific tool@version\ne.g.: `mise which npm --tool=node@20`" { @@ -430,12 +435,11 @@ cmd "which" { } arg "" help="The bin name to look up" } -cmd "render-completion" hide=true { +cmd "render-completion" hide=true help="Generate shell completions" { flag "-s,--shell" help="Shell type to generate completions for" hide=true { arg "" } arg "[SHELL]" help="Shell type to generate completions for" } -cmd "render-help" hide=true -cmd "render-mangen" hide=true - +cmd "render-help" hide=true help="internal command to generate markdown from help" +cmd "render-mangen" hide=true help="internal command to generate markdown from help" diff --git a/src/parse/cmd.rs b/src/parse/cmd.rs index 8f9a85e..86bc348 100644 --- a/src/parse/cmd.rs +++ b/src/parse/cmd.rs @@ -52,6 +52,30 @@ impl From<&SchemaCmd> for KdlNode { let children = node.children_mut().get_or_insert_with(KdlDocument::new); children.nodes_mut().push(aliases); } + if let Some(help) = &cmd.help { + node.entries_mut() + .push(KdlEntry::new_prop("help", help.clone())); + } + if let Some(help) = &cmd.long_help { + node.entries_mut() + .push(KdlEntry::new_prop("long_help", help.clone())); + } + if let Some(help) = &cmd.before_help { + node.entries_mut() + .push(KdlEntry::new_prop("before_help", help.clone())); + } + if let Some(help) = &cmd.before_long_help { + node.entries_mut() + .push(KdlEntry::new_prop("before_long_help", help.clone())); + } + if let Some(help) = &cmd.after_help { + node.entries_mut() + .push(KdlEntry::new_prop("after_help", help.clone())); + } + if let Some(help) = &cmd.after_long_help { + node.entries_mut() + .push(KdlEntry::new_prop("after_long_help", help.clone())); + } for flag in &cmd.flags { let children = node.children_mut().get_or_insert_with(KdlDocument::new); children.nodes_mut().push(flag.into()); diff --git a/src/parse/spec.rs b/src/parse/spec.rs index a7a585b..3a21994 100644 --- a/src/parse/spec.rs +++ b/src/parse/spec.rs @@ -21,6 +21,10 @@ pub struct Spec { pub cmd: SchemaCmd, pub config: SpecConfig, pub version: Option, + pub usage: String, + + pub about: Option, + pub long_about: Option, } impl Spec { @@ -150,6 +154,26 @@ impl Display for Spec { node.push(KdlEntry::new(self.bin.clone())); nodes.push(node); } + if let Some(version) = &self.version { + let mut node = KdlNode::new("version"); + node.push(KdlEntry::new(version.clone())); + nodes.push(node); + } + if let Some(about) = &self.about { + let mut node = KdlNode::new("about"); + node.push(KdlEntry::new(about.clone())); + nodes.push(node); + } + if let Some(long_about) = &self.long_about { + let mut node = KdlNode::new("long_about"); + node.push(KdlEntry::new(long_about.clone())); + nodes.push(node); + } + if !self.usage.is_empty() { + let mut node = KdlNode::new("usage"); + node.push(KdlEntry::new(self.usage.clone())); + nodes.push(node); + } for flag in self.cmd.flags.iter() { nodes.push(flag.into()); } @@ -170,10 +194,13 @@ impl Display for Spec { impl From<&clap::Command> for Spec { fn from(cmd: &clap::Command) -> Self { Spec { - bin: cmd.get_bin_name().unwrap_or_default().to_string(), name: cmd.get_name().to_string(), + bin: cmd.get_bin_name().unwrap_or(cmd.get_name()).to_string(), cmd: cmd.into(), version: cmd.get_version().map(|v| v.to_string()), + about: cmd.get_about().map(|a| a.to_string()), + long_about: cmd.get_long_about().map(|a| a.to_string()), + usage: cmd.clone().render_usage().to_string(), ..Default::default() } }