dnrops
/
mise
mirror of https://github.com/jdx/mise
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

feat: improving task docs and cli reference docs (#2678) 

* feat: improving task docs

* Commit from GitHub Actions (test)

---------

Co-authored-by: mise[bot] <123107610+mise-en-dev@users.noreply.github.com>
This commit is contained in:
jdx 2024-09-28 19:06:25 -05:00 committed by GitHub
parent 3b94bc5c60
commit 453c61f2d8
111 changed files with 1679 additions and 3533 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.markdownlintignore
View File

@ -1,6 +1,7 @@
registry/
target/
/registry/
/target/
CHANGELOG.md
docs/node_modules/
node_modules/
test/
/tasks.md

8
.mise.toml
View File

@ -23,6 +23,7 @@ direnv = "latest"
actionlint = "latest"
ripgrep = "latest"
"pipx:toml-sort" = "latest"
usage = "latest"
#python = { version = "latest", virtualenv = "{{env.HOME}}/.cache/venv" }
#ruby = "3.1"
@ -49,7 +50,12 @@ run = "cargo build --color always --all-features"
[tasks."render:usage"]
depends = ["build"]
env = { CLICOLOR_FORCE = "0" }
run = "mise usage > mise.usage.kdl"
run = [
"mise usage > mise.usage.kdl",
"mise g task-docs > tasks.md",
"usage g md -f mise.usage.kdl -m --out-dir docs/cli --url-prefix /cli --html-encode",
"markdownlint --fix docs/cli",
]
[tasks."render:completions"]
depends = ["build", "render:usage"]

1
.mise/tasks/filetask
View File

@ -3,6 +3,7 @@
#USAGE flag "-f --force" help="Overwrite existing <file>"
#USAGE flag "-u --user <user>" help="User to run as"
#USAGE arg "<file>" help="The file to write" default="file.txt"
#USAGE arg "<arg_with_default>" help="An arg with a default" default="mydefault"
# mise description="This is a test build script"
# mise depends=["lint", "build"]

3
.mise/tasks/test/coverage
View File

@ -28,9 +28,6 @@ elif [[ "${TEST_TRANCHE:-}" == 1 ]]; then
y=$((y - 1))
fi
mise self-update -fy "$y.$m.0"
elif [[ "${TEST_TRANCHE:-}" == 2 ]]; then
echo "::group::render"
MISE_EXPERIMENTAL=1 mise run render
elif [[ "${TEST_TRANCHE:-}" == 3 ]]; then
echo "::group::Unit tests"
cargo test --all-features

13
Cargo.lock generated
View File

@ -2575,9 +2575,9 @@ checksum = "953ec861398dccce10c670dfeaf3ec4911ca479e9c02154b3a215178c5f566f2"
[[package]]
name = "portable-atomic"
version = "1.8.0"
version = "1.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d30538d42559de6b034bc76fd6dd4c38961b1ee5c6c56e3808c50128fdbc22ce"
checksum = "cc9c68a3f6da06753e9335d63e27f6b9754dd1920d941135b7ea8224f141adb2"
[[package]]
name = "powerfmt"
@ -3611,9 +3611,9 @@ dependencies = [
[[package]]
name = "tempfile"
version = "3.12.0"
version = "3.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "04cbcdd0c794ebb0d4cf35e88edd2f7d2c4c3e9a5a6dab322839b321c6a87a64"
checksum = "f0f2c9fc62d0beef6951ccffd757e241266a2c833136efbe35af6cd2567dca5b"
dependencies = [
"cfg-if",
"fastrand",
@ -4106,9 +4106,9 @@ checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da"
[[package]]
name = "usage-lib"
version = "0.8.0"
version = "0.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4d2f461138354b775e96629ce474dad0f7b9996dd902db85665de06b8a2aaeda"
checksum = "f1ea55fc767a5cbeffacb5740c9e68aea2a78109820bf6ff83fa1b76948ea637"
dependencies = [
"clap",
"heck 0.5.0",
@ -4118,6 +4118,7 @@ dependencies = [
"log",
"miette",
"once_cell",
"regex",
"serde",
"strum",
"tera",

4
Cargo.toml
View File

@ -115,8 +115,8 @@ tokio = { version = "1.37.0", features = [
toml = { version = "0.8", features = ["parse"] }
toml_edit = { version = "0.22", features = ["parse"] }
url = "2.5.0"
#usage-lib = { path = "../usage/lib" }
usage-lib = { version = "0.8.0", features = ["clap", "docs"] }
# usage-lib = { path = "../usage/lib", features = ["clap", "docs"] }
usage-lib = { version = "0.8", features = ["clap", "docs"] }
versions = { version = "6.2.0", features = ["serde"] }
vfox = "0.1"
walkdir = "2.5.0"

201
docs/.vitepress/config.ts
View File

@ -1,137 +1,133 @@
import { defineConfig } from 'vitepress'
import { Command, commands } from './cli_commands'
import { defineConfig } from "vitepress";
import { Command, commands } from "./cli_commands";
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "mise-en-place",
description: "mise-en-place documentation",
lang: 'en-US',
lang: "en-US",
lastUpdated: true,
appearance: 'dark',
appearance: "dark",
sitemap: {
hostname: 'https://mise.jdx.dev',
hostname: "https://mise.jdx.dev",
},
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
outline: 'deep',
outline: "deep",
nav: [
{text: 'Dev Tools', link: '/dev-tools/'},
{text: 'Environments', link: '/environments'},
{text: 'Tasks', link: '/tasks/'},
{ text: "Dev Tools", link: "/dev-tools/" },
{ text: "Environments", link: "/environments" },
{ text: "Tasks", link: "/tasks/" },
],
sidebar: [
{text: 'Getting Started', link: '/getting-started'},
{text: 'About', link: '/about'},
{text: 'Configuration', link: '/configuration'},
{text: 'Continuous Integration', link: '/continuous-integration'},
{text: 'Demo', link: '/demo'},
{text: 'FAQs', link: '/faq'},
{text: 'How I Use mise', link: '/how-i-use-mise'},
{text: 'IDE Integration', link: '/ide-integration'},
{text: 'Paranoid', link: '/paranoid'},
{text: 'Registry', link: '/registry'},
{text: 'Settings', link: '/settings'},
{text: 'Plugins', link: '/plugins'},
{text: 'Coming from rtx', link: '/rtx'},
{text: 'Team', link: '/team'},
{text: 'Contributing', link: '/contributing'},
{text: 'Tips & Tricks', link: '/tips-and-tricks'},
{ text: "Getting Started", link: "/getting-started" },
{ text: "About", link: "/about" },
{ text: "Configuration", link: "/configuration" },
{ text: "Continuous Integration", link: "/continuous-integration" },
{ text: "Demo", link: "/demo" },
{ text: "FAQs", link: "/faq" },
{ text: "How I Use mise", link: "/how-i-use-mise" },
{ text: "IDE Integration", link: "/ide-integration" },
{ text: "Paranoid", link: "/paranoid" },
{ text: "Registry", link: "/registry" },
{ text: "Settings", link: "/settings" },
{ text: "Plugins", link: "/plugins" },
{ text: "Coming from rtx", link: "/rtx" },
{ text: "Team", link: "/team" },
{ text: "Contributing", link: "/contributing" },
{ text: "Tips & Tricks", link: "/tips-and-tricks" },
{
text: 'Dev Tools',
link: '/dev-tools/',
text: "Dev Tools",
link: "/dev-tools/",
items: [
{text: 'Aliases', link: '/dev-tools/aliases'},
{text: 'Comparison to asdf', link: '/dev-tools/comparison-to-asdf'},
{text: 'Shims', link: '/dev-tools/shims'},
{ text: "Aliases", link: "/dev-tools/aliases" },
{ text: "Comparison to asdf", link: "/dev-tools/comparison-to-asdf" },
{ text: "Shims", link: "/dev-tools/shims" },
{
text: 'Backends',
link: '/dev-tools/backends/',
text: "Backends",
link: "/dev-tools/backends/",
items: [
{text: 'asdf', link: '/dev-tools/backends/asdf'},
{text: 'cargo', link: '/dev-tools/backends/cargo'},
{text: 'go', link: '/dev-tools/backends/go'},
{text: 'npm', link: '/dev-tools/backends/npm'},
{text: 'pipx', link: '/dev-tools/backends/pipx'},
{text: 'spm', link: '/dev-tools/backends/spm'},
{text: 'ubi', link: '/dev-tools/backends/ubi'},
{text: 'vfox', link: '/dev-tools/backends/vfox'},
]
}
{ text: "asdf", link: "/dev-tools/backends/asdf" },
{ text: "cargo", link: "/dev-tools/backends/cargo" },
{ text: "go", link: "/dev-tools/backends/go" },
{ text: "npm", link: "/dev-tools/backends/npm" },
{ text: "pipx", link: "/dev-tools/backends/pipx" },
{ text: "spm", link: "/dev-tools/backends/spm" },
{ text: "ubi", link: "/dev-tools/backends/ubi" },
{ text: "vfox", link: "/dev-tools/backends/vfox" },
],
},
],
},
{
text: 'Environments',
link: '/environments',
text: "Environments",
link: "/environments",
items: [
{text: 'direnv', link: '/direnv'},
{text: 'Profiles', link: '/profiles'},
{text: 'Templates', link: '/templates'},
{ text: "direnv", link: "/direnv" },
{ text: "Profiles", link: "/profiles" },
{ text: "Templates", link: "/templates" },
],
},
{
text: 'Tasks',
link: '/tasks/',
text: "Tasks",
link: "/tasks/",
items: [
{text: 'Running Tasks', link: '/tasks/running-tasks'},
{text: 'File Tasks', link: '/tasks/file-tasks'},
{text: 'TOML Tasks', link: '/tasks/toml-tasks'},
{ text: "Running Tasks", link: "/tasks/running-tasks" },
{ text: "File Tasks", link: "/tasks/file-tasks" },
{ text: "TOML Tasks", link: "/tasks/toml-tasks" },
],
},
{
text: 'Languages',
text: "Languages",
items: [
{text: 'Bun', link: '/lang/bun'},
{text: 'Deno', link: '/lang/deno'},
{text: 'Erlang', link: '/lang/erlang'},
{text: 'Go', link: '/lang/go'},
{text: 'Java', link: '/lang/java'},
{text: 'Node.js', link: '/lang/node'},
{text: 'Python', link: '/lang/python'},
{text: 'Ruby', link: '/lang/ruby'},
{text: 'Rust', link: '/lang/rust'},
]
},
{
text: 'Internals',
items: [
{text: 'Cache Behavior', link: '/cache-behavior'},
{text: 'Directory Structure', link: '/directories'},
{text: 'Project Roadmap', link: '/project-roadmap'},
{ text: "Bun", link: "/lang/bun" },
{ text: "Deno", link: "/lang/deno" },
{ text: "Erlang", link: "/lang/erlang" },
{ text: "Go", link: "/lang/go" },
{ text: "Java", link: "/lang/java" },
{ text: "Node.js", link: "/lang/node" },
{ text: "Python", link: "/lang/python" },
{ text: "Ruby", link: "/lang/ruby" },
{ text: "Rust", link: "/lang/rust" },
],
},
{
text: 'CLI Reference',
link: '/cli/',
text: "Internals",
items: [
{text: 'Global Flags', link: '/cli/global-flags'},
...cliReference(commands),
]
{ text: "Cache Behavior", link: "/cache-behavior" },
{ text: "Directory Structure", link: "/directories" },
{ text: "Project Roadmap", link: "/project-roadmap" },
],
},
{
text: "CLI Reference",
link: "/cli/",
items: cliReference(commands),
},
],
socialLinks: [
{icon: 'github', link: 'https://github.com/jdx/mise'}
],
socialLinks: [{ icon: "github", link: "https://github.com/jdx/mise" }],
editLink: {
pattern: 'https://github.com/jdx/mise/edit/main/docs/:path',
pattern: "https://github.com/jdx/mise/edit/main/docs/:path",
},
search: {
provider: 'algolia',
provider: "algolia",
options: {
indexName: 'rtx',
appId: '1452G4RPSJ',
apiKey: 'ad09b96a7d2a30eddc2771800da7a1cf',
indexName: "rtx",
appId: "1452G4RPSJ",
apiKey: "ad09b96a7d2a30eddc2771800da7a1cf",
insights: true,
}
},
},
footer: {
message: 'Licensed under the MIT License. Maintained by <a href="https://github.com/jdx">@jdx</a> and <a href="https://github.com/jdx/mise/graphs/contributors">friends</a>.',
message:
'Licensed under the MIT License. Maintained by <a href="https://github.com/jdx">@jdx</a> and <a href="https://github.com/jdx/mise/graphs/contributors">friends</a>.',
copyright: 'Copyright © 2024 <a href="https://github.com/jdx">@jdx</a>',
},
carbonAds: {
code: 'CWYIPKQN',
placement: 'misejdxdev',
code: "CWYIPKQN",
placement: "misejdxdev",
},
},
markdown: {
@ -141,19 +137,22 @@ export default defineConfig({
},
head: [
[
'script',
{async: '', src: 'https://www.googletagmanager.com/gtag/js?id=G-B69G389C8T'}
"script",
{
async: "",
src: "https://www.googletagmanager.com/gtag/js?id=G-B69G389C8T",
},
],
[
'script',
"script",
{},
`window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-B69G389C8T');`
]
gtag('config', 'G-B69G389C8T');`,
],
],
})
});
function cliReference(commands: { [key: string]: Command }) {
return Object.keys(commands)
@ -161,17 +160,21 @@ function cliReference(commands: { [key: string]: Command }) {
.filter(([name, command]) => command.hide !== true)
.map(([name, command]) => {
const x: any = {
text: name,
text: `mise ${name}`,
};
if (command.subcommands) {
x.collapsed = true;
x.items = Object.keys(command.subcommands).map((subcommand) => ({
text: subcommand,
link: `/cli/${name}/${subcommand}`,
}));
x.items = Object.keys(command.subcommands)
.filter(
(subcommand) => command.subcommands![subcommand].hide !== true,
)
.map((subcommand) => ({
text: `mise ${name} ${subcommand}`,
link: `/cli/${name}/${subcommand}`,
}));
} else {
x.link = `/cli/${name}`;
}
return x;
})
});
}

39
docs/cli/activate.md
View File

@ -1,6 +1,5 @@
## `mise activate [OPTIONS] [SHELL_TYPE]`
# `mise activate [--shims] [-q --quiet] [SHELL_TYPE]`
```text
Initializes mise in the current shell session
This should go into your shell's rc file.
@ -22,27 +21,27 @@ specify the full path like this:
Customize status output with `status` settings.
Usage: activate [OPTIONS] [SHELL_TYPE]
## Arguments
Arguments:
[SHELL_TYPE]
Shell type to generate the script for
[possible values: bash, fish, nu, xonsh, zsh]
### `[SHELL_TYPE]`
Options:
--shims
Use shims instead of modifying PATH
Effectively the same as:
PATH="$HOME/.local/share/mise/shims:$PATH"
Shell type to generate the script for
-q, --quiet
Suppress non-error messages
## Flags
### `--shims`
Use shims instead of modifying PATH
Effectively the same as:
PATH="$HOME/.local/share/mise/shims:$PATH"
### `-q --quiet`
Suppress non-error messages
Examples:
$ eval "$(mise activate bash)"
$ eval "$(mise activate zsh)"
$ mise activate fish | source
$ execx($(mise activate xonsh))
```
eval "$(mise activate bash)"
eval "$(mise activate zsh)"
mise activate fish | source
execx($(mise activate xonsh))

22
docs/cli/alias.md Normal file
View File

@ -0,0 +1,22 @@
# `mise alias [-p --plugin <PLUGIN>] [--no-header] [subcommand]`
**Aliases**: a
Manage aliases
## Flags
### `-p --plugin <PLUGIN>`
filter aliases by plugin
### `--no-header`
Don't show table header
## Subcommands
* [`mise alias get <PLUGIN> <ALIAS>`](/cli/alias/get.md)
* [`mise alias ls [--no-header] [PLUGIN]`](/cli/alias/ls.md)
* [`mise alias set <args>…`](/cli/alias/set.md)
* [`mise alias unset <PLUGIN> <ALIAS>`](/cli/alias/unset.md)

19
docs/cli/alias/get.md
View File

@ -1,20 +1,19 @@
## `mise alias get <PLUGIN> <ALIAS>`
# `mise alias get <PLUGIN> <ALIAS>`
```text
Show an alias for a plugin
This is the contents of an alias.<PLUGIN> entry in ~/.config/mise/config.toml
This is the contents of an alias.&lt;PLUGIN> entry in ~/.config/mise/config.toml
Usage: alias get <PLUGIN> <ALIAS>
## Arguments
Arguments:
<PLUGIN>
The plugin to show the alias for
### `<PLUGIN>`
<ALIAS>
The alias to show
The plugin to show the alias for
### `<ALIAS>`
The alias to show
Examples:
$ mise alias get node lts-hydrogen
20.0.0
```

26
docs/cli/alias/ls.md
View File

@ -1,29 +1,29 @@
## `mise alias ls [OPTIONS] [PLUGIN]`
# `mise alias ls [--no-header] [PLUGIN]`
**Aliases:** `list`
**Aliases**: list
```text
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"
[alias.node]
lts = "20.0.0"
Usage: alias ls [OPTIONS] [PLUGIN]
## Arguments
Arguments:
[PLUGIN]
Show aliases for <PLUGIN>
### `[PLUGIN]`
Options:
--no-header
Don't show table header
Show aliases for &lt;PLUGIN>
## Flags
### `--no-header`
Don't show table header
Examples:
$ mise aliases
node lts-hydrogen 20.0.0
```

26
docs/cli/alias/set.md
View File

@ -1,25 +1,25 @@
## `mise alias set <PLUGIN> <ALIAS> <VALUE>`
# `mise alias set <args>…`
**Aliases:** `add, create`
**Aliases**: add, create
```text
Add/update an alias for a plugin
This modifies the contents of ~/.config/mise/config.toml
Usage: alias set <PLUGIN> <ALIAS> <VALUE>
## Arguments
Arguments:
<PLUGIN>
The plugin to set the alias for
### `<PLUGIN>`
<ALIAS>
The alias to set
The plugin to set the alias for
<VALUE>
The value to set the alias to
### `<ALIAS>`
The alias to set
### `<VALUE>`
The value to set the alias to
Examples:
$ mise alias set node lts-hydrogen 18.0.0
```
mise alias set node lts-hydrogen 18.0.0

21
docs/cli/alias/unset.md
View File

@ -1,22 +1,21 @@
## `mise alias unset <PLUGIN> <ALIAS>`
# `mise alias unset <PLUGIN> <ALIAS>`
**Aliases:** `del, delete, remove, rm`
**Aliases**: rm, remove, delete, del
```text
Clears an alias for a plugin
This modifies the contents of ~/.config/mise/config.toml
Usage: alias unset <PLUGIN> <ALIAS>
## Arguments
Arguments:
<PLUGIN>
The plugin to remove the alias from
### `<PLUGIN>`
<ALIAS>
The alias to remove
The plugin to remove the alias from
### `<ALIAS>`
The alias to remove
Examples:
$ mise alias unset node lts-hydrogen
```
mise alias unset node lts-hydrogen

11
docs/cli/asdf.md
View File

@ -1,11 +0,0 @@
## `mise asdf [ARGS]...`
```text
[internal] simulates asdf for plugins that call "asdf" internally
Usage: asdf [ARGS]...
Arguments:
[ARGS]...
all arguments
```

9
docs/cli/backends.md Normal file
View File

@ -0,0 +1,9 @@
# `mise backends [subcommand]`
**Aliases**: b
Manage backends
## Subcommands
* [`mise backends ls`](/cli/backends/ls.md)

22
docs/cli/backends/ls.md
View File

@ -1,19 +1,15 @@
## `mise backends ls`
# `mise backends ls`
**Aliases:** `list`
**Aliases**: list
```text
List built-in backends
Usage: backends ls
Examples:
$ mise backends ls
cargo
go
npm
pipx
spm
ubi
```
$ mise backends ls
cargo
go
npm
pipx
spm
ubi

6
docs/cli/bin-paths.md
View File

@ -1,7 +1,3 @@
## `mise bin-paths`
# `mise bin-paths`
```text
List all the active runtime bin paths
Usage: bin-paths
```

10
docs/cli/cache.md Normal file
View File

@ -0,0 +1,10 @@
# `mise cache [subcommand]`
Manage the mise cache
Run `mise cache` with no args to view the current cache directory.
## Subcommands
* [`mise cache clear [PLUGIN]...`](/cli/cache/clear.md)
* [`mise cache prune [--dry-run] [-v --verbose...] [PLUGIN]...`](/cli/cache/prune.md)

14
docs/cli/cache/clear.md vendored
View File

@ -1,13 +1,11 @@
## `mise cache clear [PLUGIN]...`
# `mise cache clear [PLUGIN]...`
**Aliases:** `c`
**Aliases**: c
```text
Deletes all cache files in mise
Usage: cache clear [PLUGIN]...
## Arguments
Arguments:
[PLUGIN]...
Plugin(s) to clear cache for e.g.: node, python
```
### `[PLUGIN]...`
Plugin(s) to clear cache for e.g.: node, python

27
docs/cli/cache/prune.md vendored
View File

@ -1,23 +1,24 @@
## `mise cache prune [OPTIONS] [PLUGIN]...`
# `mise cache prune [--dry-run] [-v --verbose...] [PLUGIN]...`
**Aliases:** `p`
**Aliases**: p
```text
Removes stale mise cache files
By default, this command will remove files that have not been accessed in 30 days.
Change this with the MISE_CACHE_PRUNE_AGE environment variable.
Usage: cache prune [OPTIONS] [PLUGIN]...
## Arguments
Arguments:
[PLUGIN]...
Plugin(s) to clear cache for e.g.: node, python
### `[PLUGIN]...`
Options:
--dry-run
Just show what would be pruned
Plugin(s) to clear cache for e.g.: node, python
-v, --verbose...
Show pruned files
```
## Flags
### `--dry-run`
Just show what would be pruned
### `-v --verbose...`
Show pruned files

20
docs/cli/completion.md
View File

@ -1,19 +1,15 @@
## `mise completion [SHELL]`
# `mise completion [SHELL]`
```text
Generate shell completions
Usage: completion [SHELL]
## Arguments
Arguments:
[SHELL]
Shell type to generate completions for
[possible values: bash, fish, zsh]
### `[SHELL]`
Shell type to generate completions for
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
```
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

18
docs/cli/config.md Normal file
View File

@ -0,0 +1,18 @@
# `mise config [--no-header] [subcommand]`
**Aliases**: cfg
Manage config files
## Flags
### `--no-header`
Do not print table header
## Subcommands
* [`mise config generate [-o --output <OUTPUT>]`](/cli/config/generate.md)
* [`mise config get [-f --file <FILE>] [KEY]`](/cli/config/get.md)
* [`mise config ls [--no-header]`](/cli/config/ls.md)
* [`mise config set [-f --file <FILE>] [-t --type <TYPE>] <KEY> <VALUE>`](/cli/config/set.md)

18
docs/cli/config/generate.md
View File

@ -1,18 +1,16 @@
## `mise config generate [OPTIONS]` <Badge type="warning" text="experimental" />
# `mise config generate [-o --output <OUTPUT>]`
**Aliases:** `g`
**Aliases**: g
```text
[experimental] Generate a mise.toml file
Usage: config generate [OPTIONS]
## Flags
Options:
-o, --output <OUTPUT>
Output to file instead of stdout
### `-o --output <OUTPUT>`
Output to file instead of stdout
Examples:
$ mise cf generate > .mise.toml
$ mise cf generate --output=.mise.toml
```
mise cf generate > .mise.toml
mise cf generate --output=.mise.toml

24
docs/cli/config/get.md
View File

@ -1,22 +1,22 @@
## `mise config get [OPTIONS] [KEY]`
# `mise config get [-f --file <FILE>] [KEY]`
```text
Display the value of a setting in a mise.toml file
Usage: config get [OPTIONS] [KEY]
## Arguments
Arguments:
[KEY]
The path of the config to display
### `[KEY]`
Options:
-f, --file <FILE>
The path to the mise.toml file to edit
If not provided, the nearest mise.toml file will be used
The path of the config to display
## Flags
### `-f --file <FILE>`
The path to the mise.toml file to edit
If not provided, the nearest mise.toml file will be used
Examples:
$ mise toml get tools.python
3.12
```

14
docs/cli/config/ls.md
View File

@ -1,15 +1,13 @@
## `mise config ls [OPTIONS]`
# `mise config ls [--no-header]`
```text
List config files currently in use
Usage: config ls [OPTIONS]
## Flags
Options:
--no-header
Do not print table header
### `--no-header`
Do not print table header
Examples:
$ mise config ls
```
mise config ls

39
docs/cli/config/set.md
View File

@ -1,30 +1,29 @@
## `mise config set [OPTIONS] <KEY> <VALUE>`
# `mise config set [-f --file <FILE>] [-t --type <TYPE>] <KEY> <VALUE>`
```text
Display the value of a setting in a mise.toml file
Usage: config set [OPTIONS] <KEY> <VALUE>
## Arguments
Arguments:
<KEY>
The path of the config to display
### `<KEY>`
<VALUE>
The value to set the key to
The path of the config to display
Options:
-f, --file <FILE>
The path to the mise.toml file to edit
If not provided, the nearest mise.toml file will be used
### `<VALUE>`
-t, --type <TYPE>
[default: string]
[possible values: string, integer, float, bool]
The value to set the key to
## Flags
### `-f --file <FILE>`
The path to the mise.toml file to edit
If not provided, the nearest mise.toml file will be used
### `-t --type <TYPE>`
Examples:
$ mise config set tools.python 3.12
$ mise config set settings.always_keep_download true
$ mise config set env.TEST_ENV_VAR ABC
```
mise config set tools.python 3.12
mise config set settings.always_keep_download true
mise config set env.TEST_ENV_VAR ABC

13
docs/cli/current.md
View File

@ -1,18 +1,18 @@
## `mise current [PLUGIN]`
# `mise current [PLUGIN]`
```text
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.
Usage: current [PLUGIN]
## Arguments
Arguments:
[PLUGIN]
Plugin to show versions of e.g.: ruby, node, cargo:eza, npm:prettier, etc
### `[PLUGIN]`
Plugin to show versions of e.g.: ruby, node, cargo:eza, npm:prettier, etc
Examples:
# outputs `.tool-versions` compatible format
$ mise current
python 3.11.0 3.10.0
@ -26,4 +26,3 @@ Examples:
# can output multiple versions
$ mise current python
3.11.0 3.10.0
```

8
docs/cli/deactivate.md
View File

@ -1,13 +1,9 @@
## `mise deactivate`
# `mise deactivate`
```text
Disable mise for current shell session
This can be used to temporarily disable mise in a shell session.
Usage: deactivate
Examples:
$ mise deactivate
```
mise deactivate

13
docs/cli/direnv.md Normal file
View File

@ -0,0 +1,13 @@
# `mise direnv [subcommand]`
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.
## Subcommands
* [`mise direnv activate`](/cli/direnv/activate.md)

14
docs/cli/direnv/activate.md
View File

@ -1,19 +1,15 @@
## `mise direnv activate`
# `mise direnv activate`
```text
Output direnv function to use mise inside direnv
See https://mise.jdx.dev/direnv.html for more information
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.
Usage: direnv activate
Examples:
$ mise direnv activate > ~/.config/direnv/lib/use_mise.sh
$ echo 'use mise' > .envrc
$ direnv allow
```
mise direnv activate > ~/.config/direnv/lib/use_mise.sh
echo 'use mise' > .envrc
direnv allow

8
docs/cli/direnv/envrc.md
View File

@ -1,8 +0,0 @@
## `mise direnv envrc`
```text
[internal] This is an internal command that writes an envrc file
for direnv to consume.
Usage: direnv envrc
```

8
docs/cli/direnv/exec.md
View File

@ -1,8 +0,0 @@
## `mise direnv exec`
```text
[internal] This is an internal command that writes an envrc file
for direnv to consume.
Usage: direnv exec
```

8
docs/cli/doctor.md
View File

@ -1,14 +1,10 @@
## `mise doctor`
# `mise doctor`
**Aliases:** `dr`
**Aliases**: dr
```text
Check mise installation for possible problems
Usage: doctor
Examples:
$ mise doctor
[WARN] plugin node is not installed
```

37
docs/cli/env.md
View File

@ -1,32 +1,31 @@
## `mise env [OPTIONS] [TOOL@VERSION]...`
# `mise env [-J --json] [-s --shell <SHELL>] [TOOL@VERSION]...`
**Aliases:** `e`
**Aliases**: e
```text
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.
Usage: env [OPTIONS] [TOOL@VERSION]...
## Arguments
Arguments:
[TOOL@VERSION]...
Tool(s) to use
### `[TOOL@VERSION]...`
Options:
-J, --json
Output in JSON format
Tool(s) to use
-s, --shell <SHELL>
Shell type to generate environment variables for
[possible values: bash, fish, nu, xonsh, zsh]
## Flags
### `-J --json`
Output in JSON format
### `-s --shell <SHELL>`
Shell type to generate environment variables for
Examples:
$ eval "$(mise env -s bash)"
$ eval "$(mise env -s zsh)"
$ mise env -s fish | source
$ execx($(mise env -s xonsh))
```
eval "$(mise env -s bash)"
eval "$(mise env -s zsh)"
mise env -s fish | source
execx($(mise env -s xonsh))

43
docs/cli/exec.md
View File

@ -1,39 +1,41 @@
## `mise exec [OPTIONS] [TOOL@VERSION]... [-- <COMMAND>...]`
# `mise exec [flags] [TOOL@VERSION]... [COMMAND]...`
**Aliases:** `x`
**Aliases**: x
```text
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 <RUNTIME> args
Tools will be loaded from .mise.toml/.tool-versions, though they can be overridden with &lt;RUNTIME> 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.
Usage: exec [OPTIONS] [TOOL@VERSION]... [-- <COMMAND>...]
## Arguments
Arguments:
[TOOL@VERSION]...
Tool(s) to start e.g.: node@20 python@3.10
### `[TOOL@VERSION]...`
[COMMAND]...
Command string to execute (same as --command)
Tool(s) to start e.g.: node@20 python@3.10
Options:
-c, --command <C>
Command string to execute
### `[COMMAND]...`
-j, --jobs <JOBS>
Number of jobs to run in parallel
[default: 4]
[env: MISE_JOBS=]
Command string to execute (same as --command)
--raw
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1
## Flags
### `-c --command <C>`
Command string to execute
### `-j --jobs <JOBS>`
Number of jobs to run in parallel
[default: 4]
### `--raw`
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1
Examples:
@ -45,4 +47,3 @@ Examples:
# Run a command in a different directory:
$ mise x -C /path/to/project node@20 -- node ./app.js
```

11
docs/cli/generate.md Normal file
View File

@ -0,0 +1,11 @@
# `mise generate [subcommand]`
**Aliases**: g
[experimental] Generate files for various tools/services
## Subcommands
* [`mise generate git-pre-commit [flags]`](/cli/generate/git-pre-commit.md)
* [`mise generate github-action [flags]`](/cli/generate/github-action.md)
* [`mise generate task-docs [flags]`](/cli/generate/task-docs.md)

32
docs/cli/generate/git-pre-commit.md
View File

@ -1,31 +1,27 @@
## `mise generate git-pre-commit [OPTIONS]` <Badge type="warning" text="experimental" />
# `mise generate git-pre-commit [flags]`
**Aliases:** `pre-commit`
**Aliases**: pre-commit
```text
[experimental] Generate a git pre-commit hook
This command generates a git pre-commit hook that runs a mise task like `mise run pre-commit`
when you commit changes to your repository.
Usage: generate git-pre-commit [OPTIONS]
## Flags
Options:
--hook <HOOK>
Which hook to generate (saves to .git/hooks/$hook)
[default: pre-commit]
### `--hook <HOOK>`
-t, --task <TASK>
The task to run when the pre-commit hook is triggered
[default: pre-commit]
Which hook to generate (saves to .git/hooks/$hook)
-w, --write
write to .git/hooks/pre-commit and make it executable
### `-t --task <TASK>`
The task to run when the pre-commit hook is triggered
### `-w --write`
write to .git/hooks/pre-commit and make it executable
Examples:
$ mise generate git-pre-commit --write --task=pre-commit
$ git commit -m "feat: add new feature" # runs `mise run pre-commit`
```
mise generate git-pre-commit --write --task=pre-commit
git commit -m "feat: add new feature" # runs `mise run pre-commit`

32
docs/cli/generate/github-action.md
View File

@ -1,30 +1,26 @@
## `mise generate github-action [OPTIONS]` <Badge type="warning" text="experimental" />
# `mise generate github-action [flags]`
```text
[experimental] Generate a GitHub Action workflow file
This command generates a GitHub Action workflow file that runs a mise task like `mise run ci`
when you push changes to your repository.
Usage: generate github-action [OPTIONS]
## Flags
Options:
-n, --name <NAME>
the name of the workflow to generate
[default: ci]
### `-n --name <NAME>`
-t, --task <TASK>
The task to run when the workflow is triggered
[default: ci]
the name of the workflow to generate
-w, --write
write to .github/workflows/$name.yml
### `-t --task <TASK>`
The task to run when the workflow is triggered
### `-w --write`
write to .github/workflows/$name.yml
Examples:
$ mise generate github-action --write --task=ci
$ git commit -m "feat: add new feature"
$ git push # runs `mise run ci` on GitHub
```
mise generate github-action --write --task=ci
git commit -m "feat: add new feature"
git push # runs `mise run ci` on GitHub

43
docs/cli/generate/task-docs.md
View File

@ -1,28 +1,35 @@
## `mise generate task-docs [OPTIONS]` <Badge type="warning" text="experimental" />
# `mise generate task-docs [flags]`
```text
[experimental] Generate documentation for tasks in a project
Usage: generate task-docs [OPTIONS]
## Flags
Options:
-m, --multi
render each task as a separate document, requires `--output` to be a directory
### `-I --index`
-i, --inject
inserts the documentation into an existing file
This will look for a special comment, <!-- mise-tasks -->, and replace it with the generated documentation.
It will replace everything between the comment and the next comment, <!-- /mise-tasks --> so it can be
run multiple times on the same file to update the documentation.
write only an index of tasks, intended for use with `--multi`
-I, --index
write only an index of tasks, intended for use with `--multi`
### `-i --inject`
-o, --output <OUTPUT>
writes the generated docs to a file/directory
inserts the documentation into an existing file
This will look for a special comment, &lt;!-- mise-tasks -->, and replace it with the generated documentation.
It will replace everything between the comment and the next comment, &lt;!-- /mise-tasks --> so it can be
run multiple times on the same file to update the documentation.
### `-m --multi`
render each task as a separate document, requires `--output` to be a directory
### `-o --output <OUTPUT>`
writes the generated docs to a file/directory
### `-r --root <ROOT>`
root directory to search for tasks
### `-s --style <STYLE>`
Examples:
$ mise generate task-docs
```
mise generate task-docs

32
docs/cli/global-flags.md
View File

@ -1,32 +0,0 @@
# Global Flags
These flags are available for all commands in the CLI. They may not always
do anything though.
## `-C, --cd <DIR>`
Change directory before running command
## `-P, --profile <PROFILE>`
Set the profile (environment)
## `-q, --quiet`
Suppress non-error messages
## `-v, --verbose...`
Show extra output (use -vv for even more)
## `-y, --yes`
Answer yes to all confirmation prompts
## `-h, --help`
Print help (see a summary with '-h')
## `-V, --version`
Print version

52
docs/cli/global.md
View File

@ -1,52 +0,0 @@
## `mise global [OPTIONS] [TOOL@VERSION]...`
```text
Sets/gets the global tool version(s)
Displays the contents of global config after writing.
The file is `$HOME/.config/mise/config.toml` by default. It can be changed with `$MISE_GLOBAL_CONFIG_FILE`.
If `$MISE_GLOBAL_CONFIG_FILE` is set to anything that ends in `.toml`, it will be parsed as `.mise.toml`.
Otherwise, it will be parsed as a `.tool-versions` file.
Use MISE_ASDF_COMPAT=1 to default the global config to ~/.tool-versions
Use `mise local` to set a tool version locally in the current directory.
Usage: global [OPTIONS] [TOOL@VERSION]...
Arguments:
[TOOL@VERSION]...
Tool(s) to add to .tool-versions
e.g.: node@20
If this is a single tool with no version, the current value of the global
.tool-versions will be displayed
Options:
--pin
Save exact version to `~/.tool-versions`
e.g.: `mise global --pin node@20` will save `node 20.0.0` to ~/.tool-versions
--fuzzy
Save fuzzy version to `~/.tool-versions`
e.g.: `mise global --fuzzy node@20` will save `node 20` to ~/.tool-versions
this is the default behavior unless MISE_ASDF_COMPAT=1
--remove <PLUGIN>
Remove the plugin(s) from ~/.tool-versions
--path
Get the path of the global config file
Examples:
# set the current version of node to 20.x
# will use a fuzzy version (e.g.: 20) in .tool-versions file
$ mise global --fuzzy node@20
# set the current version of node to 20.x
# will use a precise version (e.g.: 20.0.0) in .tool-versions file
$ mise global --pin node@20
# show the current version of node in ~/.tool-versions
$ mise global node
20.0.0
```

16
docs/cli/hook-env.md
View File

@ -1,16 +0,0 @@
## `mise hook-env [OPTIONS]`
```text
[internal] called by activate hook to update env vars directory change
Usage: hook-env [OPTIONS]
Options:
-s, --shell <SHELL>
Shell type to generate script for
[possible values: bash, fish, nu, xonsh, zsh]
-q, --quiet
Hide warnings such as when a tool is not installed
```

17
docs/cli/hook-not-found.md
View File

@ -1,17 +0,0 @@
## `mise hook-not-found [OPTIONS] <BIN>`
```text
[internal] called by shell when a command is not found
Usage: hook-not-found [OPTIONS] <BIN>
Arguments:
<BIN>
Attempted bin to run
Options:
-s, --shell <SHELL>
Shell type to generate script for
[possible values: bash, fish, nu, xonsh, zsh]
```

17
docs/cli/implode.md
View File

@ -1,16 +1,15 @@
## `mise implode [OPTIONS]`
# `mise implode [--config] [-n --dry-run]`
```text
Removes mise CLI and all related data
Skips config directory by default.
Usage: implode [OPTIONS]
## Flags
Options:
--config
Also remove config directory
### `--config`
-n, --dry-run
List directories that would be removed without actually removing them
```
Also remove config directory
### `-n --dry-run`
List directories that would be removed without actually removing them

2115
docs/cli/index.md
View File

File diff suppressed because it is too large Load Diff

53
docs/cli/install.md
View File

@ -1,8 +1,7 @@
## `mise install [OPTIONS] [TOOL@VERSION]...`
# `mise install [flags] [TOOL@VERSION]...`
**Aliases:** `i`
**Aliases**: i
```text
Install a tool version
Installs a tool version to `~/.local/share/mise/installs/<PLUGIN>/<VERSION>`
@ -13,34 +12,36 @@ Alternatively, run `mise exec <TOOL>@<VERSION> -- <COMMAND>` to execute a tool w
Tools will be installed in parallel. To disable, set `--jobs=1` or `MISE_JOBS=1`
Usage: install [OPTIONS] [TOOL@VERSION]...
## Arguments
Arguments:
[TOOL@VERSION]...
Tool(s) to install e.g.: node@20
### `[TOOL@VERSION]...`
Options:
-f, --force
Force reinstall even if already installed
Tool(s) to install e.g.: node@20
-j, --jobs <JOBS>
Number of jobs to run in parallel
[default: 4]
[env: MISE_JOBS=]
## Flags
--raw
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1
### `-f --force`
-v, --verbose...
Show installation output
This argument will print plugin output such as download, configuration, and compilation output.
Force reinstall even if already installed
### `-j --jobs <JOBS>`
Number of jobs to run in parallel
[default: 4]
### `--raw`
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1
### `-v --verbose...`
Show installation output
This argument will print plugin output such as download, configuration, and compilation output.
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
```
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

20
docs/cli/latest.md
View File

@ -1,17 +1,18 @@
## `mise latest [OPTIONS] <TOOL@VERSION>`
# `mise latest [-i --installed] <TOOL@VERSION>`
```text
Gets the latest available version for a plugin
Usage: latest [OPTIONS] <TOOL@VERSION>
## Arguments
Arguments:
<TOOL@VERSION>
Tool to get the latest version of
### `<TOOL@VERSION>`
Options:
-i, --installed
Show latest installed instead of available version
Tool to get the latest version of
## Flags
### `-i --installed`
Show latest installed instead of available version
Examples:
@ -20,4 +21,3 @@ Examples:
$ mise latest node # get the latest stable version of node
20.0.0
```

30
docs/cli/link.md
View File

@ -1,28 +1,31 @@
## `mise link [OPTIONS] <TOOL@VERSION> <PATH>`
# `mise link [-f --force] <TOOL@VERSION> <PATH>`
**Aliases:** `ln`
**Aliases**: ln
```text
Symlinks a tool version into mise
Use this for adding installs either custom compiled outside
mise or built with a different tool.
Usage: link [OPTIONS] <TOOL@VERSION> <PATH>
## Arguments
Arguments:
<TOOL@VERSION>
Tool name and version to create a symlink for
### `<TOOL@VERSION>`
<PATH>
The local path to the tool version
e.g.: ~/.nvm/versions/node/v20.0.0
Tool name and version to create a symlink for
Options:
-f, --force
Overwrite an existing tool version if it exists
### `<PATH>`
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
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
@ -31,4 +34,3 @@ Examples:
$ brew install node
$ mise link node@brew $(brew --prefix node)
$ mise use node@brew
```

56
docs/cli/local.md
View File

@ -1,56 +0,0 @@
## `mise local [OPTIONS] [TOOL@VERSION]...`
```text
Sets/gets tool version in local .tool-versions or .mise.toml
Use this to set a tool's version when within a directory
Use `mise global` to set a tool version globally
This uses `.tool-version` by default unless there is a `.mise.toml` file or if `MISE_USE_TOML`
is set. A future v2 release of mise will default to using `.mise.toml`.
Usage: local [OPTIONS] [TOOL@VERSION]...
Arguments:
[TOOL@VERSION]...
Tool(s) to add to .tool-versions/.mise.toml
e.g.: node@20
if this is a single tool with no version,
the current value of .tool-versions/.mise.toml will be displayed
Options:
-p, --parent
Recurse up to find a .tool-versions file rather than using the current directory only
by default this command will only set the tool in the current directory ("$PWD/.tool-versions")
--pin
Save exact version to `.tool-versions`
e.g.: `mise local --pin node@20` will save `node 20.0.0` to .tool-versions
--fuzzy
Save fuzzy version to `.tool-versions` e.g.: `mise local --fuzzy node@20` will save `node 20` to .tool-versions This is the default behavior unless MISE_ASDF_COMPAT=1
--remove <PLUGIN>
Remove the plugin(s) from .tool-versions
--path
Get the path of the config file
Examples:
# set the current version of node to 20.x for the current directory
# will use a precise version (e.g.: 20.0.0) in .tool-versions file
$ mise local node@20
# set node to 20.x for the current project (recurses up to find .tool-versions)
$ mise local -p node@20
# set the current version of node to 20.x for the current directory
# will use a fuzzy version (e.g.: 20) in .tool-versions file
$ mise local --fuzzy node@20
# removes node from .tool-versions
$ mise local --remove=node
# show the current version of node in .tool-versions
$ mise local node
20.0.0
```

27
docs/cli/ls-remote.md
View File

@ -1,24 +1,26 @@
## `mise ls-remote [OPTIONS] [TOOL@VERSION] [PREFIX]`
# `mise ls-remote [--all] [TOOL@VERSION] [PREFIX]`
```text
List runtime versions available for install
note that the results are cached
run `mise cache clean` to clear the cache and get fresh results
Usage: ls-remote [OPTIONS] [TOOL@VERSION] [PREFIX]
## Arguments
Arguments:
[TOOL@VERSION]
Plugin to get versions for
### `[TOOL@VERSION]`
[PREFIX]
The version prefix to use when querying the latest version
same as the first argument after the "@"
Plugin to get versions for
Options:
--all
Show all installed plugins and versions
### `[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
Examples:
@ -33,4 +35,3 @@ Examples:
$ mise ls-remote node 20
20.0.0
20.1.0
```

52
docs/cli/ls.md
View File

@ -1,8 +1,7 @@
## `mise ls [OPTIONS] [PLUGIN]...`
# `mise ls [flags] [PLUGIN]...`
**Aliases:** `list`
**Aliases**: list
```text
List installed and active tool versions
This command lists tools that mise "knows about".
@ -11,33 +10,41 @@ that are in a config file (active) but may or may not be installed.
It's a useful command to get the current state of your tools.
Usage: ls [OPTIONS] [PLUGIN]...
## Arguments
Arguments:
[PLUGIN]...
Only show tool versions from [PLUGIN]
### `[PLUGIN]...`
Options:
-c, --current
Only show tool versions currently specified in a .tool-versions/.mise.toml
Only show tool versions from [PLUGIN]
-g, --global
Only show tool versions currently specified in a the global .tool-versions/.mise.toml
## Flags
-i, --installed
Only show tool versions that are installed (Hides tools defined in .tool-versions/.mise.toml but not installed)
### `-c --current`
-J, --json
Output in JSON format
Only show tool versions currently specified in a .tool-versions/.mise.toml
-m, --missing
Display missing tool versions
### `-g --global`
--prefix <PREFIX>
Display versions matching this prefix
Only show tool versions currently specified in a the global .tool-versions/.mise.toml
--no-header
Don't display headers
### `-i --installed`
Only show tool versions that are installed (Hides tools defined in .tool-versions/.mise.toml but not installed)
### `-J --json`
Output in JSON format
### `-m --missing`
Display missing tool versions
### `--prefix <PREFIX>`
Display versions matching this prefix
### `--no-header`
Don't display headers
Examples:
@ -64,4 +71,3 @@ Examples:
],
"python": [...]
}
```

44
docs/cli/outdated.md
View File

@ -1,30 +1,33 @@
## `mise outdated [OPTIONS] [TOOL@VERSION]...`
# `mise outdated [flags] [TOOL@VERSION]...`
```text
Shows outdated tool versions
Usage: outdated [OPTIONS] [TOOL@VERSION]...
## Arguments
Arguments:
[TOOL@VERSION]...
Tool(s) to show outdated versions for
e.g.: node@20 python@3.10
If not specified, all tools in global and local configs will be shown
### `[TOOL@VERSION]...`
Options:
-l, --bump
Compares against the latest versions available, not what matches the current config
For example, if you have `node = "20"` in your config by default `mise outdated` will only
show other 20.x versions, not 21.x or 22.x versions.
Using this flag, if there are 21.x or newer versions it will display those instead of 20.x.
Tool(s) to show outdated versions for
e.g.: node@20 python@3.10
If not specified, all tools in global and local configs will be shown
-J, --json
Output in JSON format
## Flags
--no-header
Don't show table header
### `-l --bump`
Compares against the latest versions available, not what matches the current config
For example, if you have `node = "20"` in your config by default `mise outdated` will only
show other 20.x versions, not 21.x or 22.x versions.
Using this flag, if there are 21.x or newer versions it will display those instead of 20.x.
### `-J --json`
Output in JSON format
### `--no-header`
Don't show table header
Examples:
@ -39,4 +42,3 @@ Examples:
$ mise outdated --json
{"python": {"requested": "3.11", "current": "3.11.0", "latest": "3.11.1"}, ...}
```

33
docs/cli/plugins.md Normal file
View File

@ -0,0 +1,33 @@
# `mise plugins [flags] [subcommand]`
**Aliases**: p
Manage plugins
## Flags
### `-c --core`
The built-in plugins only
Normally these are not shown
### `--user`
List installed plugins
This is the default behavior but can be used with --core
to show core and user plugins
### `-u --urls`
Show the git url for each plugin
e.g.: <https://github.com/asdf-vm/asdf-nodejs.git>
## Subcommands
* [`mise plugins install [flags] [NEW_PLUGIN] [GIT_URL]`](/cli/plugins/install.md)
* [`mise plugins link [-f --force] <NAME> [PATH]`](/cli/plugins/link.md)
* [`mise plugins ls [flags]`](/cli/plugins/ls.md)
* [`mise plugins ls-remote [-u --urls] [--only-names]`](/cli/plugins/ls-remote.md)
* [`mise plugins uninstall [-p --purge] [-a --all] [PLUGIN]...`](/cli/plugins/uninstall.md)
* [`mise plugins update [-j --jobs <JOBS>] [PLUGIN]...`](/cli/plugins/update.md)

45
docs/cli/plugins/install.md
View File

@ -1,8 +1,7 @@
## `mise plugins install [OPTIONS] [NEW_PLUGIN] [GIT_URL]`
# `mise plugins install [flags] [NEW_PLUGIN] [GIT_URL]`
**Aliases:** `a, add, i`
**Aliases**: i, a, add
```text
Install a plugin
note that mise automatically can install plugins when you install a tool
@ -10,28 +9,33 @@ e.g.: `mise install node@20` will autoinstall the node plugin
This behavior can be modified in ~/.config/mise/config.toml
Usage: plugins install [OPTIONS] [NEW_PLUGIN] [GIT_URL]
## Arguments
Arguments:
[NEW_PLUGIN]
The name of the plugin to install
e.g.: node, ruby
Can specify multiple plugins: `mise plugins install node ruby python`
### `[NEW_PLUGIN]`
[GIT_URL]
The git url of the plugin
The name of the plugin to install
e.g.: node, ruby
Can specify multiple plugins: `mise plugins install node ruby python`
Options:
-f, --force
Reinstall even if plugin exists
### `[GIT_URL]`
-a, --all
Install all missing plugins
This will only install plugins that have matching shorthands.
i.e.: they don't need the full git repo url
The git url of the plugin
-v, --verbose...
Show installation output
## Flags
### `-f --force`
Reinstall even if plugin exists
### `-a --all`
Install all missing plugins
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
Examples:
# install the node via shorthand
@ -46,4 +50,3 @@ Examples:
# install the node plugin using a specific ref
$ mise plugins install node https://github.com/mise-plugins/rtx-nodejs.git#v1.0.0
```

31
docs/cli/plugins/link.md
View File

@ -1,26 +1,28 @@
## `mise plugins link [OPTIONS] <NAME> [PATH]`
# `mise plugins link [-f --force] <NAME> [PATH]`
**Aliases:** `ln`
**Aliases**: ln
```text
Symlinks a plugin into mise
This is used for developing a plugin.
Usage: plugins link [OPTIONS] <NAME> [PATH]
## Arguments
Arguments:
<NAME>
The name of the plugin
e.g.: node, ruby
### `<NAME>`
[PATH]
The local path to the plugin
e.g.: ./mise-node
The name of the plugin
e.g.: node, ruby
Options:
-f, --force
Overwrite existing plugin
### `[PATH]`
The local path to the plugin
e.g.: ./mise-node
## Flags
### `-f --force`
Overwrite existing plugin
Examples:
# essentially just `ln -s ./mise-node ~/.local/share/mise/plugins/node`
@ -28,4 +30,3 @@ Examples:
# infer plugin name as "node"
$ mise plugins link ./mise-node
```

20
docs/cli/plugins/ls-remote.md
View File

@ -1,22 +1,20 @@
## `mise plugins ls-remote [OPTIONS]`
# `mise plugins ls-remote [-u --urls] [--only-names]`
**Aliases:** `list-all, list-remote`
**Aliases**: list-remote, list-all
```text
List all available remote plugins
The full list is here: https://github.com/jdx/mise/blob/main/src/default_shorthands.rs
The full list is here: <https://github.com/jdx/mise/blob/main/src/default_shorthands.rs>
Examples:
$ mise plugins ls-remote
## Flags
Usage: plugins ls-remote [OPTIONS]
### `-u --urls`
Options:
-u, --urls
Show the git url for each plugin e.g.: https://github.com/mise-plugins/mise-poetry.git
Show the git url for each plugin e.g.: <https://github.com/mise-plugins/mise-poetry.git>
--only-names
Only show the name of each plugin by default it will show a "*" next to installed plugins
```
### `--only-names`
Only show the name of each plugin by default it will show a "*" next to installed plugins

34
docs/cli/plugins/ls.md
View File

@ -1,28 +1,29 @@
## `mise plugins ls [OPTIONS]`
# `mise plugins ls [flags]`
**Aliases:** `list`
**Aliases**: list
```text
List installed plugins
Can also show remotely available plugins to install.
Usage: plugins ls [OPTIONS]
## Flags
Options:
-c, --core
The built-in plugins only
Normally these are not shown
### `-c --core`
--user
List installed plugins
This is the default behavior but can be used with --core
to show core and user plugins
The built-in plugins only
Normally these are not shown
-u, --urls
Show the git url for each plugin
e.g.: https://github.com/asdf-vm/asdf-nodejs.git
### `--user`
List installed plugins
This is the default behavior but can be used with --core
to show core and user plugins
### `-u --urls`
Show the git url for each plugin
e.g.: <https://github.com/asdf-vm/asdf-nodejs.git>
Examples:
@ -33,4 +34,3 @@ Examples:
$ mise plugins ls --urls
node https://github.com/asdf-vm/asdf-nodejs.git
ruby https://github.com/asdf-vm/asdf-ruby.git
```

29
docs/cli/plugins/uninstall.md
View File

@ -1,24 +1,25 @@
## `mise plugins uninstall [OPTIONS] [PLUGIN]...`
# `mise plugins uninstall [-p --purge] [-a --all] [PLUGIN]...`
**Aliases:** `remove, rm`
**Aliases**: remove, rm
```text
Removes a plugin
Usage: plugins uninstall [OPTIONS] [PLUGIN]...
## Arguments
Arguments:
[PLUGIN]...
Plugin(s) to remove
### `[PLUGIN]...`
Options:
-p, --purge
Also remove the plugin's installs, downloads, and cache
Plugin(s) to remove
-a, --all
Remove all plugins
## Flags
### `-p --purge`
Also remove the plugin's installs, downloads, and cache
### `-a --all`
Remove all plugins
Examples:
$ mise uninstall node
```
mise uninstall node

30
docs/cli/plugins/update.md
View File

@ -1,26 +1,26 @@
## `mise plugins update [OPTIONS] [PLUGIN]...`
# `mise plugins update [-j --jobs <JOBS>] [PLUGIN]...`
**Aliases:** `up, upgrade`
**Aliases**: up, upgrade
```text
Updates a plugin to the latest version
note: this updates the plugin itself, not the runtime versions
Usage: plugins update [OPTIONS] [PLUGIN]...
## Arguments
Arguments:
[PLUGIN]...
Plugin(s) to update
### `[PLUGIN]...`
Options:
-j, --jobs <JOBS>
Number of jobs to run in parallel
Default: 4
Plugin(s) to update
## Flags
### `-j --jobs <JOBS>`
Number of jobs to run in parallel
Default: 4
Examples:
$ mise plugins update # update all plugins
$ mise plugins update node # update only node
$ mise plugins update node#beta # specify a ref
```
mise plugins update # update all plugins
mise plugins update node # update only node
mise plugins update node#beta # specify a ref

30
docs/cli/prune.md
View File

@ -1,6 +1,5 @@
## `mise prune [OPTIONS] [PLUGIN]...`
# `mise prune [flags] [PLUGIN]...`
```text
Delete unused versions of tools
mise tracks which config files have been used in ~/.local/share/mise/tracked_config_files
@ -8,25 +7,28 @@ Versions which are no longer the latest specified in any of those configs are de
Versions installed only with environment variables (`MISE_<PLUGIN>_VERSION`) will be deleted,
as will versions only referenced on the command line (`mise exec <PLUGIN>@<VERSION>`).
Usage: prune [OPTIONS] [PLUGIN]...
## Arguments
Arguments:
[PLUGIN]...
Prune only versions from this plugin(s)
### `[PLUGIN]...`
Options:
-n, --dry-run
Do not actually delete anything
Prune only versions from this plugin(s)
--configs
Prune only tracked and trusted configuration links that point to non-existent configurations
## Flags
--tools
Prune only unused versions of tools
### `-n --dry-run`
Do not actually delete anything
### `--configs`
Prune only tracked and trusted configuration links that point to non-existent configurations
### `--tools`
Prune only unused versions of tools
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
```

6
docs/cli/registry.md
View File

@ -1,14 +1,10 @@
## `mise registry` <Badge type="warning" text="experimental" />
# `mise registry`
```text
[experimental] List available tools
Usage: registry
Examples:
$ mise registry
node core:node
poetry asdf:mise-plugins/mise-poetry
ubi cargo:ubi
```

7
docs/cli/render-help.md
View File

@ -1,7 +0,0 @@
## `mise render-help`
```text
internal command to generate markdown from help
Usage: render-help
```

7
docs/cli/render-mangen.md
View File

@ -1,7 +0,0 @@
## `mise render-mangen`
```text
internal command to generate markdown from help
Usage: render-mangen
```

6
docs/cli/reshim.md
View File

@ -1,6 +1,5 @@
## `mise reshim`
# `mise reshim`
```text
rebuilds the shim farm
This creates new shims in ~/.local/share/mise/shims for CLIs that have been added.
@ -17,11 +16,8 @@ npm() {
mise reshim
}
Usage: reshim
Examples:
$ mise reshim
$ ~/.local/share/mise/shims/node -v
v20.0.0
```

77
docs/cli/run.md
View File

@ -1,8 +1,7 @@
## `mise run [OPTIONS] [TASK] [ARGS]...` <Badge type="warning" text="experimental" />
# `mise run [flags]`
**Aliases:** `r`
**Aliases**: r
```text
[experimental] Run a tasks
This command will run a tasks, or multiple tasks in parallel.
@ -29,55 +28,50 @@ The name of the script will be the name of the tasks.
EOF
$ mise run build
Usage: run [OPTIONS] [TASK] [ARGS]...
## Flags
Arguments:
[TASK]
Tasks to run
Can specify multiple tasks by separating with `:::`
e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2
[default: default]
### `-C --cd <CD>`
[ARGS]...
Arguments to pass to the tasks. Use ":::" to separate tasks
Change to this directory before executing the command
Options:
-C, --cd <CD>
Change to this directory before executing the command
### `-n --dry-run`
-n, --dry-run
Don't actually run the tasks(s), just print them in order of execution
Don't actually run the tasks(s), just print them in order of execution
-f, --force
Force the tasks to run even if outputs are up to date
### `-f --force`
-p, --prefix
Print stdout/stderr by line, prefixed with the tasks's label
Defaults to true if --jobs > 1
Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
Force the tasks to run even if outputs are up to date
-i, --interleave
Print directly to stdout/stderr instead of by line
Defaults to true if --jobs == 1
Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
### `-p --prefix`
-t, --tool <TOOL@VERSION>
Tool(s) to also add e.g.: node@20 python@3.10
Print stdout/stderr by line, prefixed with the tasks's label
Defaults to true if --jobs > 1
Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
-j, --jobs <JOBS>
Number of tasks to run in parallel
[default: 4]
Configure with `jobs` config or `MISE_JOBS` env var
[env: MISE_JOBS=]
### `-i --interleave`
-r, --raw
Read/write directly to stdin/stdout/stderr instead of by line
Configure with `raw` config or `MISE_RAW` env var
Print directly to stdout/stderr instead of by line
Defaults to true if --jobs == 1
Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
--timings
Shows elapsed time after each tasks
### `-t --tool... <TOOL@VERSION>`
Tool(s) to also add e.g.: node@20 python@3.10
### `-j --jobs <JOBS>`
Number of tasks to run in parallel
[default: 4]
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
### `--timings`
Shows elapsed time after each tasks
Examples:
@ -97,4 +91,3 @@ Examples:
# Execute multiple tasks each with their own arguments.
$ mise tasks cmd1 arg1 arg2 ::: cmd2 arg1 arg2
```

30
docs/cli/self-update.md
View File

@ -1,25 +1,27 @@
## `mise self-update [OPTIONS] [VERSION]`
# `mise self-update [flags] [VERSION]`
```text
Updates mise itself
Uses the GitHub Releases API to find the latest release and binary.
By default, this will also update any installed plugins.
Uses the `GITHUB_API_TOKEN` environment variable if set for higher rate limits.
Usage: self-update [OPTIONS] [VERSION]
## Arguments
Arguments:
[VERSION]
Update to a specific version
### `[VERSION]`
Options:
-f, --force
Update even if already up to date
Update to a specific version
--no-plugins
Disable auto-updating plugins
## Flags
-y, --yes
Skip confirmation prompt
```
### `-f --force`
Update even if already up to date
### `--no-plugins`
Disable auto-updating plugins
### `-y --yes`
Skip confirmation prompt

31
docs/cli/set.md
View File

@ -1,25 +1,27 @@
## `mise set [OPTIONS] [ENV_VARS]...`
# `mise set [--file <FILE>] [-g --global] [ENV_VARS]...`
```text
Manage environment variables
By default this command modifies ".mise.toml" in the current directory.
Usage: set [OPTIONS] [ENV_VARS]...
## Arguments
Arguments:
[ENV_VARS]...
Environment variable(s) to set
e.g.: NODE_ENV=production
### `[ENV_VARS]...`
Options:
--file <FILE>
The TOML file to update
Defaults to MISE_DEFAULT_CONFIG_FILENAME environment variable, or ".mise.toml".
Environment variable(s) to set
e.g.: NODE_ENV=production
-g, --global
Set the environment variable in the global config file
## Flags
### `--file <FILE>`
The TOML file to update
Defaults to MISE_DEFAULT_CONFIG_FILENAME environment variable, or ".mise.toml".
### `-g --global`
Set the environment variable in the global config file
Examples:
@ -31,4 +33,3 @@ Examples:
$ mise set
key value source
NODE_ENV production ~/.config/mise/config.toml
```

16
docs/cli/settings.md Normal file
View File

@ -0,0 +1,16 @@
# `mise settings [--keys] [subcommand]`
Manage settings
## Flags
### `--keys`
Only display key names for each setting
## Subcommands
* [`mise settings get <SETTING>`](/cli/settings/get.md)
* [`mise settings ls [--keys]`](/cli/settings/ls.md)
* [`mise settings set <SETTING> <VALUE>`](/cli/settings/set.md)
* [`mise settings unset <SETTING>`](/cli/settings/unset.md)

12
docs/cli/settings/get.md
View File

@ -1,6 +1,5 @@
## `mise settings get <SETTING>`
# `mise settings get <SETTING>`
```text
Show a current setting
This is the contents of a single entry in ~/.config/mise/config.toml
@ -8,14 +7,13 @@ 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`
Usage: settings get <SETTING>
## Arguments
Arguments:
<SETTING>
The setting to show
### `<SETTING>`
The setting to show
Examples:
$ mise settings get legacy_version_file
true
```

14
docs/cli/settings/ls.md
View File

@ -1,8 +1,7 @@
## `mise settings ls [OPTIONS]`
# `mise settings ls [--keys]`
**Aliases:** `list`
**Aliases**: list
```text
Show current settings
This is the contents of ~/.config/mise/config.toml
@ -10,14 +9,13 @@ This is the contents of ~/.config/mise/config.toml
Note that aliases are also stored in this file
but managed separately with `mise aliases`
Usage: settings ls [OPTIONS]
## Flags
Options:
--keys
Only display key names for each setting
### `--keys`
Only display key names for each setting
Examples:
$ mise settings
legacy_version_file = false
```

21
docs/cli/settings/set.md
View File

@ -1,22 +1,21 @@
## `mise settings set <SETTING> <VALUE>`
# `mise settings set <SETTING> <VALUE>`
**Aliases:** `add, create`
**Aliases**: add, create
```text
Add/update a setting
This modifies the contents of ~/.config/mise/config.toml
Usage: settings set <SETTING> <VALUE>
## Arguments
Arguments:
<SETTING>
The setting to set
### `<SETTING>`
<VALUE>
The value to set
The setting to set
### `<VALUE>`
The value to set
Examples:
$ mise settings set legacy_version_file true
```
mise settings set legacy_version_file true

16
docs/cli/settings/unset.md
View File

@ -1,19 +1,17 @@
## `mise settings unset <SETTING>`
# `mise settings unset <SETTING>`
**Aliases:** `del, delete, remove, rm`
**Aliases**: rm, remove, delete, del
```text
Clears a setting
This modifies the contents of ~/.config/mise/config.toml
Usage: settings unset <SETTING>
## Arguments
Arguments:
<SETTING>
The setting to remove
### `<SETTING>`
The setting to remove
Examples:
$ mise settings unset legacy_version_file
```
mise settings unset legacy_version_file

36
docs/cli/shell.md
View File

@ -1,8 +1,7 @@
## `mise shell [OPTIONS] [TOOL@VERSION]...`
# `mise shell [flags] [TOOL@VERSION]...`
**Aliases:** `sh`
**Aliases**: sh
```text
Sets a tool version for the current session
Only works in a session where mise is already activated.
@ -11,28 +10,29 @@ This works by setting environment variables for the current shell session
such as `MISE_NODE_VERSION=20` which is "eval"ed as a shell function created
by `mise activate`.
Usage: shell [OPTIONS] [TOOL@VERSION]...
## Arguments
Arguments:
[TOOL@VERSION]...
Tool(s) to use
### `[TOOL@VERSION]...`
Options:
-j, --jobs <JOBS>
Number of jobs to run in parallel
[default: 4]
[env: MISE_JOBS=]
Tool(s) to use
--raw
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1
## Flags
-u, --unset
Removes a previously set version
### `-j --jobs <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
Examples:
$ mise shell node@20
$ node -v
v20.0.0
```

8
docs/cli/sync.md Normal file
View File

@ -0,0 +1,8 @@
# `mise sync [subcommand]`
Add tool versions from external tools to mise
## Subcommands
* [`mise sync node [flags]`](/cli/sync/node.md)
* [`mise sync python <--pyenv>`](/cli/sync/python.md)

28
docs/cli/sync/node.md
View File

@ -1,25 +1,25 @@
## `mise sync node <--brew|--nvm|--nodenv>`
# `mise sync node [flags]`
```text
Symlinks all tool versions from an external tool into mise
For example, use this to import all Homebrew node installs into mise
Usage: sync node <--brew|--nvm|--nodenv>
## Flags
Options:
--brew
Get tool versions from Homebrew
### `--brew`
--nvm
Get tool versions from nvm
Get tool versions from Homebrew
--nodenv
Get tool versions from nodenv
### `--nvm`
Get tool versions from nvm
### `--nodenv`
Get tool versions from nodenv
Examples:
$ brew install node@18 node@20
$ mise sync node --brew
$ mise use -g node@18 - uses Homebrew-provided node
```
brew install node@18 node@20
mise sync node --brew
mise use -g node@18 - uses Homebrew-provided node

18
docs/cli/sync/python.md
View File

@ -1,19 +1,17 @@
## `mise sync python --pyenv`
# `mise sync python <--pyenv>`
```text
Symlinks all tool versions from an external tool into mise
For example, use this to import all pyenv installs into mise
Usage: sync python --pyenv
## Flags
Options:
--pyenv
Get tool versions from pyenv
### `--pyenv`
Get tool versions from pyenv
Examples:
$ pyenv install 3.11.0
$ mise sync python --pyenv
$ mise use -g python@3.11.0 - uses pyenv-provided python
```
pyenv install 3.11.0
mise sync python --pyenv
mise use -g python@3.11.0 - uses pyenv-provided python

43
docs/cli/tasks.md Normal file
View File

@ -0,0 +1,43 @@
# `mise tasks [flags] [subcommand]`
**Aliases**: t
[experimental] Manage tasks
## Flags
### `--no-header`
Do not print table header
### `-x --extended`
Show all columns
### `--hidden`
Show hidden tasks
### `--sort <COLUMN>`
Sort by column. Default is name.
### `--sort-order <SORT_ORDER>`
Sort order. Default is asc.
### `-J --json`
Output in JSON format
## Subcommands
* [`mise tasks deps [--hidden] [--dot] [TASKS]...`](/cli/tasks/deps.md)
* [`mise tasks edit [-p --path] <TASK>`](/cli/tasks/edit.md)
* [`mise tasks info [-J --json] <TASK>`](/cli/tasks/info.md)
* [`mise tasks ls [flags]`](/cli/tasks/ls.md)
* [`mise tasks run [flags] [TASK] [ARGS]...`](/cli/tasks/run.md)
Examples:
mise tasks ls

29
docs/cli/tasks/deps.md
View File

@ -1,22 +1,24 @@
## `mise tasks deps [OPTIONS] [TASKS]...` <Badge type="warning" text="experimental" />
# `mise tasks deps [--hidden] [--dot] [TASKS]...`
```text
[experimental] Display a tree visualization of a dependency graph
Usage: tasks deps [OPTIONS] [TASKS]...
## Arguments
Arguments:
[TASKS]...
Tasks to show dependencies for
Can specify multiple tasks by separating with spaces
e.g.: mise tasks deps lint test check
### `[TASKS]...`
Options:
--hidden
Show hidden tasks
Tasks to show dependencies for
Can specify multiple tasks by separating with spaces
e.g.: mise tasks deps lint test check
--dot
Display dependencies in DOT format
## Flags
### `--hidden`
Show hidden tasks
### `--dot`
Display dependencies in DOT format
Examples:
@ -28,4 +30,3 @@ Examples:
# Show dependencies in DOT format
$ mise tasks deps --dot
```

24
docs/cli/tasks/edit.md
View File

@ -1,22 +1,22 @@
## `mise tasks edit [OPTIONS] <TASK>` <Badge type="warning" text="experimental" />
# `mise tasks edit [-p --path] <TASK>`
```text
[experimental] Edit a tasks with $EDITOR
The tasks will be created as a standalone script if it does not already exist.
Usage: tasks edit [OPTIONS] <TASK>
## Arguments
Arguments:
<TASK>
Tasks to edit
### `<TASK>`
Options:
-p, --path
Display the path to the tasks instead of editing it
Tasks to edit
## Flags
### `-p --path`
Display the path to the tasks instead of editing it
Examples:
$ mise tasks edit build
$ mise tasks edit test
```
mise tasks edit build
mise tasks edit test

20
docs/cli/tasks/info.md
View File

@ -1,17 +1,18 @@
## `mise tasks info [OPTIONS] <TASK>` <Badge type="warning" text="experimental" />
# `mise tasks info [-J --json] <TASK>`
```text
[experimental] Get information about a task
Usage: tasks info [OPTIONS] <TASK>
## Arguments
Arguments:
<TASK>
Name of the task to get information about
### `<TASK>`
Options:
-J, --json
Output in JSON format
Name of the task to get information about
## Flags
### `-J --json`
Output in JSON format
Examples:
@ -40,4 +41,3 @@ Examples:
"file": null,
"usage_spec": {}
}
```

47
docs/cli/tasks/ls.md
View File

@ -1,40 +1,39 @@
## `mise tasks ls [OPTIONS]` <Badge type="warning" text="experimental" />
# `mise tasks ls [flags]`
```text
[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
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.
Usage: tasks ls [OPTIONS]
## Flags
Options:
--no-header
Do not print table header
### `--no-header`
-x, --extended
Show all columns
Do not print table header
--hidden
Show hidden tasks
### `-x --extended`
--sort <COLUMN>
Sort by column. Default is name.
[possible values: name, alias, description, source]
Show all columns
--sort-order <SORT_ORDER>
Sort order. Default is asc.
[possible values: asc, desc]
### `--hidden`
-J, --json
Output in JSON format
Show hidden tasks
### `--sort <COLUMN>`
Sort by column. Default is name.
### `--sort-order <SORT_ORDER>`
Sort order. Default is asc.
### `-J --json`
Output in JSON format
Examples:
$ mise tasks ls
```
mise tasks ls

89
docs/cli/tasks/run.md
View File

@ -1,8 +1,7 @@
## `mise tasks run [OPTIONS] [TASK] [ARGS]...` <Badge type="warning" text="experimental" />
# `mise tasks run [flags] [TASK] [ARGS]...`
**Aliases:** `r`
**Aliases**: r
```text
[experimental] Run a tasks
This command will run a tasks, or multiple tasks in parallel.
@ -29,55 +28,62 @@ The name of the script will be the name of the tasks.
EOF
$ mise run build
Usage: tasks run [OPTIONS] [TASK] [ARGS]...
## Arguments
Arguments:
[TASK]
Tasks to run
Can specify multiple tasks by separating with `:::`
e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2
[default: default]
### `[TASK]`
[ARGS]...
Arguments to pass to the tasks. Use ":::" to separate tasks
Tasks to run
Can specify multiple tasks by separating with `:::`
e.g.: mise run task1 arg1 arg2 ::: task2 arg1 arg2
Options:
-C, --cd <CD>
Change to this directory before executing the command
### `[ARGS]...`
-n, --dry-run
Don't actually run the tasks(s), just print them in order of execution
Arguments to pass to the tasks. Use ":::" to separate tasks
-f, --force
Force the tasks to run even if outputs are up to date
## Flags
-p, --prefix
Print stdout/stderr by line, prefixed with the tasks's label
Defaults to true if --jobs > 1
Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
### `-C --cd <CD>`
-i, --interleave
Print directly to stdout/stderr instead of by line
Defaults to true if --jobs == 1
Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
Change to this directory before executing the command
-t, --tool <TOOL@VERSION>
Tool(s) to also add e.g.: node@20 python@3.10
### `-n --dry-run`
-j, --jobs <JOBS>
Number of tasks to run in parallel
[default: 4]
Configure with `jobs` config or `MISE_JOBS` env var
[env: MISE_JOBS=]
Don't actually run the tasks(s), just print them in order of execution
-r, --raw
Read/write directly to stdin/stdout/stderr instead of by line
Configure with `raw` config or `MISE_RAW` env var
### `-f --force`
--timings
Shows elapsed time after each tasks
Force the tasks to run even if outputs are up to date
### `-p --prefix`
Print stdout/stderr by line, prefixed with the tasks's label
Defaults to true if --jobs > 1
Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
### `-i --interleave`
Print directly to stdout/stderr instead of by line
Defaults to true if --jobs == 1
Configure with `task_output` config or `MISE_TASK_OUTPUT` env var
### `-t --tool... <TOOL@VERSION>`
Tool(s) to also add e.g.: node@20 python@3.10
### `-j --jobs <JOBS>`
Number of tasks to run in parallel
[default: 4]
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
### `--timings`
Shows elapsed time after each tasks
Examples:
@ -97,4 +103,3 @@ Examples:
# Execute multiple tasks each with their own arguments.
$ mise tasks cmd1 arg1 arg2 ::: cmd2 arg1 arg2
```

33
docs/cli/trust.md
View File

@ -1,32 +1,36 @@
## `mise trust [OPTIONS] [CONFIG_FILE]`
# `mise trust [flags] [CONFIG_FILE]`
```text
Marks a config file as trusted
This means mise will parse the file with potentially dangerous
features enabled.
This includes:
- environment variables
- templates
- `path:` plugin versions
Usage: trust [OPTIONS] [CONFIG_FILE]
## Arguments
Arguments:
[CONFIG_FILE]
The config file to trust
### `[CONFIG_FILE]`
Options:
-a, --all
Trust all config files in the current directory and its parents
The config file to trust
--untrust
No longer trust this config
## Flags
--show
Show the trusted status of config files from the current directory and its parents.
Does not trust or untrust any files.
### `-a --all`
Trust all config files in the current directory and its parents
### `--untrust`
No longer trust this config
### `--show`
Show the trusted status of config files from the current directory and its parents.
Does not trust or untrust any files.
Examples:
# trusts ~/some_dir/.mise.toml
@ -34,4 +38,3 @@ Examples:
# trusts .mise.toml in the current or parent directory
$ mise trust
```

33
docs/cli/uninstall.md
View File

@ -1,26 +1,27 @@
## `mise uninstall [OPTIONS] [INSTALLED_TOOL@VERSION]...`
# `mise uninstall [-a --all] [-n --dry-run] [INSTALLED_TOOL@VERSION]...`
**Aliases:** `remove, rm`
**Aliases**: remove, rm
```text
Removes runtime versions
Usage: uninstall [OPTIONS] [INSTALLED_TOOL@VERSION]...
## Arguments
Arguments:
[INSTALLED_TOOL@VERSION]...
Tool(s) to remove
### `[INSTALLED_TOOL@VERSION]...`
Options:
-a, --all
Delete all installed versions
Tool(s) to remove
-n, --dry-run
Do not actually delete anything
## Flags
### `-a --all`
Delete all installed versions
### `-n --dry-run`
Do not actually delete anything
Examples:
$ mise uninstall node@18.0.0 # will uninstall specific version
$ mise uninstall node # will uninstall current node version
$ mise uninstall --all node@18.0.0 # will uninstall all node versions
```
mise uninstall node@18.0.0 # will uninstall specific version
mise uninstall node # will uninstall current node version
mise uninstall --all node@18.0.0 # will uninstall all node versions

27
docs/cli/unset.md
View File

@ -1,21 +1,22 @@
## `mise unset [OPTIONS] [KEYS]...`
# `mise unset [-f --file <FILE>] [-g --global] [KEYS]...`
```text
Remove environment variable(s) from the config file
By default this command modifies ".mise.toml" in the current directory.
Usage: unset [OPTIONS] [KEYS]...
## Arguments
Arguments:
[KEYS]...
Environment variable(s) to remove
e.g.: NODE_ENV
### `[KEYS]...`
Options:
-f, --file <FILE>
Specify a file to use instead of ".mise.toml"
Environment variable(s) to remove
e.g.: NODE_ENV
-g, --global
Use the global config file
```
## Flags
### `-f --file <FILE>`
Specify a file to use instead of ".mise.toml"
### `-g --global`
Use the global config file

62
docs/cli/upgrade.md
View File

@ -1,40 +1,42 @@
## `mise upgrade [OPTIONS] [TOOL@VERSION]...`
# `mise upgrade [flags] [TOOL@VERSION]...`
**Aliases:** `up`
**Aliases**: up
```text
Upgrades outdated tool versions
Usage: upgrade [OPTIONS] [TOOL@VERSION]...
## Arguments
Arguments:
[TOOL@VERSION]...
Tool(s) to upgrade
e.g.: node@20 python@3.10
If not specified, all current tools will be upgraded
### `[TOOL@VERSION]...`
Options:
-n, --dry-run
Just print what would be done, don't actually do it
Tool(s) to upgrade
e.g.: node@20 python@3.10
If not specified, all current tools will be upgraded
-i, --interactive
Display multiselect menu to choose which tools to upgrade
## Flags
-j, --jobs <JOBS>
Number of jobs to run in parallel
[default: 4]
[env: MISE_JOBS=]
### `-n --dry-run`
-l, --bump
Upgrades to the latest version available, bumping the version in mise.toml
For example, if you have `node = "20.0.0"` in your mise.toml but 22.1.0 is the latest available,
this will install 22.1.0 and set `node = "22.1.0"` in your config.
It keeps the same precision as what was there before, so if you instead had `node = "20"`, it
would change your config to `node = "22"`.
Just print what would be done, don't actually do it
--raw
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1
```
### `-i --interactive`
Display multiselect menu to choose which tools to upgrade
### `-j --jobs <JOBS>`
Number of jobs to run in parallel
[default: 4]
### `-l --bump`
Upgrades to the latest version available, bumping the version in mise.toml
For example, if you have `node = "20.0.0"` in your mise.toml but 22.1.0 is the latest available,
this will install 22.1.0 and set `node = "22.1.0"` in your config.
It keeps the same precision as what was there before, so if you instead had `node = "20"`, it
would change your config to `node = "22"`.
### `--raw`
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1

8
docs/cli/usage.md
View File

@ -1,9 +1,5 @@
## `mise usage`
# `mise usage`
```text
Generate a usage CLI spec
See https://usage.jdx.dev for more information
Usage: usage
```
See <https://usage.jdx.dev> for more information

78
docs/cli/use.md
View File

@ -1,8 +1,7 @@
## `mise use [OPTIONS] [TOOL@VERSION]...`
# `mise use [flags] [TOOL@VERSION]...`
**Aliases:** `u`
**Aliases**: u
```text
Install tool version and add it to config
This will install the tool if it is not already installed.
@ -10,48 +9,56 @@ 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.
Usage: use [OPTIONS] [TOOL@VERSION]...
## Arguments
Arguments:
[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
### `[TOOL@VERSION]...`
Options:
-f, --force
Force reinstall even if already installed
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
--fuzzy
Save fuzzy version to config file
e.g.: `mise use --fuzzy node@20` will save 20 as the version
this is the default behavior unless MISE_ASDF_COMPAT=1
## Flags
-g, --global
Use the global config file (~/.config/mise/config.toml) instead of the local one
### `-f --force`
-e, --env <ENV>
Modify an environment-specific config file like .mise.<env>.toml
Force reinstall even if already installed
-j, --jobs <JOBS>
Number of jobs to run in parallel
[default: 4]
[env: MISE_JOBS=]
### `--fuzzy`
--raw
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1
Save fuzzy version to config file
e.g.: `mise use --fuzzy node@20` will save 20 as the version
this is the default behavior unless MISE_ASDF_COMPAT=1
--remove <PLUGIN>
Remove the plugin(s) from config file
### `-g --global`
-p, --path <PATH>
Specify a path to a config file or directory If a directory is specified, it will look for .mise.toml (default) or .tool-versions
Use the global config file (~/.config/mise/config.toml) instead of the local one
--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
### `-e --env <ENV>`
Modify an environment-specific config file like .mise.&lt;env>.toml
### `-j --jobs <JOBS>`
Number of jobs to run in parallel
[default: 4]
### `--raw`
Directly pipe stdin/stdout/stderr from plugin to user Sets --jobs=1
### `--remove... <PLUGIN>`
Remove the plugin(s) from config file
### `-p --path <PATH>`
Specify a path to a config file or directory If a directory is specified, it will look for .mise.toml (default) or .tool-versions
### `--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
Examples:
@ -68,4 +75,3 @@ Examples:
# sets .mise.staging.toml (which is used if MISE_ENV=staging)
$ mise use --env staging node@20
```

6
docs/cli/version.md
View File

@ -1,7 +1,3 @@
## `mise version`
# `mise version`
```text
Show mise version
Usage: version
```

48
docs/cli/watch.md
View File

@ -1,35 +1,35 @@
## `mise watch [OPTIONS] [ARGS]...` <Badge type="warning" text="experimental" />
# `mise watch [-t --task... <TASK>] [-g --glob... <GLOB>] [ARGS]...`
**Aliases:** `w`
**Aliases**: w
```text
[experimental] Run a tasks watching for changes
Usage: watch [OPTIONS] [ARGS]...
## Arguments
Arguments:
[ARGS]...
Extra arguments
### `[ARGS]...`
Options:
-t, --task <TASK>
Tasks to run
[default: default]
Extra arguments
-g, --glob <GLOB>
Files to watch
Defaults to sources from the tasks(s)
## Flags
### `-t --task... <TASK>`
Tasks to run
### `-g --glob... <GLOB>`
Files to watch
Defaults to sources from the tasks(s)
Examples:
$ mise watch -t build
Runs the "build" tasks. Will re-run the tasks when any of its sources change.
Uses "sources" from the tasks definition to determine which files to watch.
$ mise watch -t build --glob src/**/*.rs
Runs the "build" tasks but specify the files to watch with a glob pattern.
This overrides the "sources" from the tasks definition.
$ mise watch -t build
Runs the "build" tasks. Will re-run the tasks when any of its sources change.
Uses "sources" from the tasks definition to determine which files to watch.
$ mise run -t build --clear
Extra arguments are passed to watchexec. See `watchexec --help` for details.
```
$ mise watch -t build --glob src/**/*.rs
Runs the "build" tasks but specify the files to watch with a glob pattern.
This overrides the "sources" from the tasks definition.
$ mise run -t build --clear
Extra arguments are passed to watchexec. See `watchexec --help` for details.

20
docs/cli/where.md
View File

@ -1,19 +1,18 @@
## `mise where <TOOL@VERSION>`
# `mise where <TOOL@VERSION>`
```text
Display the installation path for a runtime
Must be installed.
Usage: where <TOOL@VERSION>
## Arguments
Arguments:
<TOOL@VERSION>
Tool(s) to look up
e.g.: ruby@3
if "@<PREFIX>" is specified, it will show the latest installed version
that matches the prefix
otherwise, it will show the current, active installed version
### `<TOOL@VERSION>`
Tool(s) to look up
e.g.: ruby@3
if "@&lt;PREFIX>" is specified, it will show the latest installed version
that matches the prefix
otherwise, it will show the current, active installed version
Examples:
# Show the latest installed version of node
@ -25,4 +24,3 @@ Examples:
# Errors if node is not referenced in any .tool-version file
$ mise where node
/home/jdx/.local/share/mise/installs/node/20.0.0
```

32
docs/cli/which.md
View File

@ -1,24 +1,27 @@
## `mise which [OPTIONS] <BIN_NAME>`
# `mise which [flags] <BIN_NAME>`
```text
Shows the path that a bin name points to
Usage: which [OPTIONS] <BIN_NAME>
## Arguments
Arguments:
<BIN_NAME>
The bin name to look up
### `<BIN_NAME>`
Options:
--plugin
Show the plugin name instead of the path
The bin name to look up
--version
Show the version instead of the path
## Flags
-t, --tool <TOOL@VERSION>
Use a specific tool@version
e.g.: `mise which npm --tool=node@20`
### `--plugin`
Show the plugin name instead of the path
### `--version`
Show the version instead of the path
### `-t --tool <TOOL@VERSION>`
Use a specific tool@version
e.g.: `mise which npm --tool=node@20`
Examples:
@ -28,4 +31,3 @@ Examples:
node
$ mise which node --version
20.0.0
```

53
mise.usage.kdl
View File

@ -86,8 +86,8 @@ 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""#
[alias.node]
lts = "20.0.0""#
after_long_help r"Examples:
$ mise aliases
@ -132,13 +132,13 @@ cmd "backends" help="Manage backends" {
alias "list"
after_long_help r"Examples:
$ mise backends ls
cargo
go
npm
pipx
spm
ubi
$ mise backends ls
cargo
go
npm
pipx
spm
ubi
"
}
}
@ -237,6 +237,7 @@ cmd "current" help="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."
after_long_help r"Examples:
# outputs `.tool-versions` compatible format
$ mise current
python 3.11.0 3.10.0
@ -392,14 +393,20 @@ when you push changes to your repository."
$ mise generate task-docs
"
flag "-m --multi" help="render each task as a separate document, requires `--output` to be a directory"
flag "-I --index" help="write only an index of tasks, intended for use with `--multi`"
flag "-i --inject" help="inserts the documentation into an existing file" {
long_help "inserts the documentation into an existing file\n\nThis will look for a special comment, <!-- mise-tasks -->, and replace it with the generated documentation.\nIt will replace everything between the comment and the next comment, <!-- /mise-tasks --> so it can be\nrun multiple times on the same file to update the documentation."
}
flag "-I --index" help="write only an index of tasks, intended for use with `--multi`"
flag "-m --multi" help="render each task as a separate document, requires `--output` to be a directory"
flag "-o --output" help="writes the generated docs to a file/directory" {
arg "<OUTPUT>"
}
flag "-r --root" help="root directory to search for tasks" {
arg "<ROOT>"
}
flag "-s --style" {
arg "<STYLE>"
}
}
}
cmd "global" hide=true help="Sets/gets the global tool version(s)" {
@ -502,6 +509,7 @@ cmd "link" help="Symlinks a tool version into mise" {
Use this for adding installs either custom compiled outside
mise or built with a different tool."
after_long_help r"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
@ -1029,7 +1037,7 @@ cmd "tasks" help="[experimental] Manage tasks" {
alias "t"
alias "task" hide=true
after_long_help r"Examples:
$ mise tasks ls
"
flag "--no-header" help="Do not print table header"
@ -1108,11 +1116,11 @@ The tasks will be created as a standalone script if it does not already exist."
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
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."
after_long_help r"Examples:
$ mise tasks ls
"
flag "--no-header" help="Do not print table header"
@ -1303,16 +1311,17 @@ cmd "version" help="Show mise version" {
cmd "watch" help="[experimental] Run a tasks watching for changes" {
alias "w"
after_long_help r#"Examples:
$ mise watch -t build
Runs the "build" tasks. Will re-run the tasks when any of its sources change.
Uses "sources" from the tasks definition to determine which files to watch.
$ mise watch -t build
Runs the "build" tasks. Will re-run the tasks when any of its sources change.
Uses "sources" from the tasks definition to determine which files to watch.
$ mise watch -t build --glob src/**/*.rs
Runs the "build" tasks but specify the files to watch with a glob pattern.
This overrides the "sources" from the tasks definition.
$ mise watch -t build --glob src/**/*.rs
Runs the "build" tasks but specify the files to watch with a glob pattern.
This overrides the "sources" from the tasks definition.
$ mise run -t build --clear
Extra arguments are passed to watchexec. See `watchexec --help` for details.
$ mise run -t build --clear
Extra arguments are passed to watchexec. See `watchexec --help` for details.
"#
flag "-t --task" help="Tasks to run" var=true {
arg "<TASK>"

4
src/cli/alias/ls.rs
View File

@ -11,8 +11,8 @@ use crate::ui::table;
///
/// For user config, aliases are defined like the following in `~/.config/mise/config.toml`:
///
/// [alias.node]
/// lts = "20.0.0"
/// [alias.node]
/// lts = "20.0.0"
#[derive(Debug, clap::Args)]
#[clap(visible_alias = "list", after_long_help = AFTER_LONG_HELP, verbatim_doc_comment)]
pub struct AliasLs {

14
src/cli/backends/ls.rs
View File

@ -22,13 +22,13 @@ impl BackendsLs {
static AFTER_LONG_HELP: &str = color_print::cstr!(
r#"<bold><underline>Examples:</underline></bold>
$ <bold>mise backends ls</bold>
cargo
go
npm
pipx
spm
ubi
$ <bold>mise backends ls</bold>
cargo
go
npm
pipx
spm
ubi
"#
);

1
src/cli/current.rs
View File

@ -100,6 +100,7 @@ impl Current {
static AFTER_LONG_HELP: &str = color_print::cstr!(
r#"<bold><underline>Examples:</underline></bold>
# outputs `.tool-versions` compatible format
$ <bold>mise current</bold>
python 3.11.0 3.10.0

12
src/cli/generate/snapshots/mise__cli__generate__task_docs__tests__task_docs.snap
View File

@ -2,8 +2,16 @@
source: src/cli/generate/task_docs.rs
expression: output
---
# `filetask`
## `filetask [--user <user>]`
## Flag `--user <user>`
* Depends: lint, test
**Aliases**: ft
This is a test build script
### Flags
#### `--user <user>`
The user to run as

40
src/cli/generate/task_docs.rs
View File

@ -7,9 +7,9 @@ use std::path::PathBuf;
#[derive(Debug, clap::Args)]
#[clap(verbatim_doc_comment, after_long_help = AFTER_LONG_HELP)]
pub struct TaskDocs {
/// render each task as a separate document, requires `--output` to be a directory
#[clap(long, short, verbatim_doc_comment)]
multi: bool,
/// write only an index of tasks, intended for use with `--multi`
#[clap(long, short = 'I', verbatim_doc_comment)]
index: bool,
/// inserts the documentation into an existing file
///
/// This will look for a special comment, <!-- mise-tasks -->, and replace it with the generated documentation.
@ -17,28 +17,43 @@ pub struct TaskDocs {
/// run multiple times on the same file to update the documentation.
#[clap(long, short, verbatim_doc_comment)]
inject: bool,
/// write only an index of tasks, intended for use with `--multi`
#[clap(long, short = 'I', verbatim_doc_comment)]
index: bool,
/// render each task as a separate document, requires `--output` to be a directory
#[clap(long, short, verbatim_doc_comment)]
multi: bool,
/// writes the generated docs to a file/directory
#[clap(long, short, verbatim_doc_comment)]
output: Option<PathBuf>,
/// root directory to search for tasks
#[clap(long, short, verbatim_doc_comment, value_hint = clap::ValueHint::DirPath)]
root: Option<PathBuf>,
#[clap(long, short, verbatim_doc_comment, value_enum, default_value_t)]
style: TaskDocsStyle,
}
#[derive(Debug, Default, Clone, clap::ValueEnum)]
enum TaskDocsStyle {
#[default]
#[value()]
Simple,
#[value()]
Detailed,
}
impl TaskDocs {
pub fn run(self) -> eyre::Result<()> {
SETTINGS.ensure_experimental("generate task-docs")?;
let tasks = CONFIG.load_tasks_in_dir(dirs::CWD.as_ref().unwrap())?;
let dir = dirs::CWD.as_ref().unwrap();
let tasks = CONFIG.load_tasks_in_dir(dir)?;
let mut out = vec![];
for task in &tasks {
out.push(task.render_markdown()?);
out.push(task.render_markdown(dir)?);
}
if let Some(output) = &self.output {
if self.multi {
if output.is_dir() {
for (i, task) in tasks.iter().enumerate() {
let path = output.join(format!("task-{}.md", i));
file::write(&path, &task.render_markdown()?)?;
let path = output.join(format!("{}.md", i));
file::write(&path, &task.render_markdown(dir)?)?;
}
} else {
return Err(eyre::eyre!(
@ -51,6 +66,7 @@ impl TaskDocs {
doc.push_str(&task);
doc.push_str("\n\n");
}
doc = format!("{}\n", doc.trim());
if self.inject {
let mut contents = file::read_to_string(output)?;
let start = contents.find("<!-- mise-tasks -->").unwrap_or(0);
@ -64,9 +80,7 @@ impl TaskDocs {
}
}
} else {
for task in out {
miseprintln!("{}", task);
}
miseprintln!("{}", out.join("\n\n").trim());
}
Ok(())
}

1
src/cli/link.rs
View File

@ -67,6 +67,7 @@ impl Link {
static AFTER_LONG_HELP: &str = color_print::cstr!(
r#"<bold><underline>Examples:</underline></bold>
# build node-20.0.0 with node-build and link it into mise
$ <bold>node-build 20.0.0 ~/.nodes/20.0.0</bold>
$ <bold>mise link node@20.0.0 ~/.nodes/20.0.0</bold>

136
src/cli/render_help.rs
View File

@ -1,5 +1,3 @@
use clap::builder::StyledStr;
use console::strip_ansi_codes;
use eyre::Result;
use indoc::formatdoc;
use itertools::Itertools;
@ -14,118 +12,13 @@ pub struct RenderHelp {}
impl RenderHelp {
pub fn run(self) -> Result<()> {
xx::file::mkdirp("docs/cli")?;
xx::file::mkdirp("docs/.vitepress")?;
let readme = file::read_to_string("docs/cli/index.md")?;
let mut current_readme = readme.split("<!-- MISE:COMMANDS -->");
let mut doc = String::new();
doc.push_str(current_readme.next().unwrap());
current_readme.next(); // discard existing commands
doc.push_str(render_commands()?.as_str());
doc.push_str(current_readme.next().unwrap());
doc = remove_trailing_spaces(&doc) + "\n";
file::write("docs/cli/index.md", &doc)?;
file::write("docs/.vitepress/cli_commands.ts", render_command_ts())?;
Ok(())
}
}
fn render_commands() -> Result<String> {
let mut cli = Cli::command()
.term_width(80)
.max_term_width(80)
.disable_help_subcommand(true)
.disable_help_flag(true);
let mut doc = formatdoc!(
r#"
<!-- MISE:COMMANDS -->
# Commands
"#
);
for command in cli
.get_subcommands_mut()
.sorted_by_cached_key(|c| c.get_name().to_string())
{
match command.has_subcommands() {
true => {
let name = command.get_name().to_string();
for subcommand in command.get_subcommands_mut() {
let output = render_command(Some(&name), subcommand);
if !subcommand.is_hide_set() {
doc.push_str(&output);
}
let output = output.trim().to_string() + "\n";
xx::file::mkdirp(format!("docs/cli/{}", name))?;
file::write(
format!("docs/cli/{}/{}.md", name, subcommand.get_name()),
&output,
)?;
}
}
false => {
let output = render_command(None, command);
if !command.is_hide_set() {
doc.push_str(&output);
}
let output = output.trim().to_string() + "\n";
file::write(format!("docs/cli/{}.md", command.get_name()), &output)?;
}
}
}
doc.push_str("<!-- MISE:COMMANDS -->");
Ok(doc)
}
fn render_command(parent: Option<&str>, c: &clap::Command) -> String {
let mut c = c.clone().disable_help_flag(true);
let strip_usage = |s: StyledStr| {
s.to_string()
.strip_prefix("Usage: ")
.unwrap_or_default()
.to_string()
};
let usage = match parent {
Some(p) => format!("{} {}", p, strip_usage(c.render_usage())),
None => strip_usage(c.render_usage()),
};
let mut c = c.override_usage(&usage);
let aliases = c.get_visible_aliases().sorted().collect_vec();
let aliases = if !aliases.is_empty() {
format!("\n**Aliases:** `{}`\n", aliases.join(", "))
} else {
String::new()
};
let about = strip_ansi_codes(&c.render_long_help().to_string())
.trim()
.to_string();
let mut badge = String::new();
if about.starts_with("[experimental]") {
badge = " <Badge type=\"warning\" text=\"experimental\" />".to_string();
}
formatdoc!(
"
## `mise {usage}`{badge}
{aliases}
```text
{about}
```
",
)
}
fn remove_trailing_spaces(s: &str) -> String {
s.lines()
.map(|line| line.trim_end().to_string())
.collect::<Vec<String>>()
.join("\n")
}
fn render_command_ts() -> String {
let mut doc = String::new();
doc.push_str(&formatdoc! {r#"
@ -180,32 +73,3 @@ fn render_command_ts() -> String {
doc.push_str("};\n");
doc
}
#[cfg(test)]
mod tests {
use std::fs;
use indoc::indoc;
use test_log::test;
use crate::file;
use crate::test::reset;
#[test]
fn test_render_help() {
reset();
file::create_dir_all("docs/cli").unwrap();
file::write(
"docs/cli/index.md",
indoc! {r#"
<!-- MISE:COMMANDS -->
<!-- MISE:COMMANDS -->
"#},
)
.unwrap();
assert_cli!("render-help");
let readme = fs::read_to_string("docs/cli/index.md").unwrap();
assert!(readme.contains("# Commands"));
file::remove_file("docs/cli/index.md").unwrap();
}
}

Some files were not shown because too many files have changed in this diff Show More