repository·main·Indexed 12 days ago
https://github.com/jdx/miseA tool manager that prepares development environments by managing dev tools, environment variables, and tasks through a single mise.toml configuration file. Written in Rust, it provides tool management for runtimes like Node.js, Go, and Python, as well as a task runner and environment variable management.
mise (pronounced "meez") is a development environment setup tool designed to provide a consistent way to set up and interact with projects regardless of the programming language used. It uses a mise.toml configuration file to manage project environments.
mise provides three main categories of functionality:
node, python, terraform). It allows you to specify different versions of these tools for different projects and supports hundreds of available tools via plugins.AWS_ACCESS_KEY_ID) that may vary between projects. It can also automatically activate tools like Python virtualenvs when you enter a project directory.The mise oci suite allows you to turn a mise.toml into a container image with one OCI layer per installed tool. This architecture ensures that updating a single tool only invalidates its specific layer, maximizing cache reuse.
| Command | Description |
|---|---|
mise oci build | Produces an OCI image layout on disk. |
mise oci run | Builds (or reuses) an image and runs a command inside it via podman/docker. |
mise oci push | Builds (or reuses) an image and pushes it to a registry. |
When running mise bootstrap over SSH with an incoming policy of deny or reject, mise performs safety checks to prevent locking you out:
SSH_CONNECTION environment variable.incoming tcp allow rule covers both the connected peer address and the server port.Escape Hatch: If you are performing a deliberately out-of-band deployment and need to bypass this check, set allow_lockout = true in your configuration.
allow_lockout = true # Use to bypass SSH safety checks during deploymentmise is a tool manager that automates the installation, version management, and environment setup for programming language runtimes (like Node.js, Python, Ruby, Go) and other development tools.
When you enter a directory or run a command, mise follows these steps:
mise.toml, .tool-versions, etc.).node@latest) using registries.PATH and environment variables.Settings cascade from broad to specific:
~/.config/mise/config.toml (Global defaults)~/work/mise.toml (Work-specific)~/work/project/mise.toml (Project-specific overrides)~/work/project/.tool-versions (Legacy asdf compatibility)You can manage the sequence and concurrency of tasks using depends, wait_for, and depends_post.
depends: Ensures the specified tasks run before the current task.wait_for: Does not add a dependency, but if the specified task is already running, the current task will wait for it to finish.depends_post: (Implicitly used for post-execution logic).You can define a task that orchestrates other tasks in series or parallel using an array of task objects:
[tasks.one_by_one]
run = [
{ task = "example1" }, # Runs example1, waits for it to finish
{ tasks = ["example2", "example3"] }, # Runs example2 and example3 in parallel
][tasks.build]
run = "echo 'build'"
[tasks.test]
run = "echo 'test'"
depends = ["build"]If a GitLab release contains multiple assets that autodetection cannot distinguish, use matching or matching_regex to narrow the selection.
Important: matching and matching_regex refine the list of candidates after autodetection has already selected the correct OS and architecture. If asset_pattern is also provided, it takes precedence and matching/matching_regex are ignored.
To install two different binaries from the same release, you must use distinct tool_alias entries so they reside in different install directories. Reusing the same gitlab:owner/repo string with different matching options will cause the second installation to overwrite the first.
# Using matching to pick a specific binary from a multi-binary release
"gitlab:owner/repo" = { version = "latest", matching = "mytool-cli" }
# Using matching_regex for precise selection
"gitlab:owner/repo" = { version = "latest", matching_regex = "^mytool-cli-" }Tasks placed in sub-directories of the default task folders are automatically prefixed with the directory name. This allows for logical grouping of related tasks.
Example structure:
mise-tasks
├── build
└── test
├── _default
├── integration
└── unitsResulting task names:
buildtest (from test/_default)test:integrationtest:unitsEdit entries allow you to manage specific parts of a file without owning the whole file. They are keyed by target_path/id.
A block is a multi-line snippet delimited by marker comments in the target file. The markers are named after the entry's id.
# for shell, -- for Lua, // for C-like). You can override this with comment = "...".A line ensures an exact single line exists in the file. It appends the line to the end if it is missing. It is idempotent and never modifies or removes other lines.
To use a template for an edit entry, pair source with template = "tera".
[dotfiles]
# A block in .zshrc
"~/.zshrc/activate" = { block = 'eval "$(mise activate zsh)"' }
# A multi-line block
"~/.zshrc/aliases" = { block = '''
alias ll='ls -l'
alias la='ls -la'
''' }
# A single line in /etc/hosts
"/etc/hosts/dev" = { line = "127.0.0.1 dev.local" }
# A templated edit
"~/.gitconfig/identity" = { source = "snippets/git-identity.tmpl", template = "tera" }When developing environment plugins (vfox modules), you can control caching behavior by returning a configuration object from the MiseEnv hook. To make a plugin cacheable and specify which files trigger an invalidation, return:
{cacheable = true, watch_files = [...]}
You can reduce boilerplate and automate project scaffolding by creating custom presets. Presets are implemented using mise tasks. By placing task scripts in ~/.config/mise/tasks/, you can define complex setup workflows that can be invoked from any directory.
To create a preset, write a shell script and use special #MISE directives to control the execution environment, such as setting the working directory (#MISE dir="{{cwd}}") or defining dependencies (#MISE depends=["preset:name"]).
# Example of a preset task script
#!/usr/bin/env bash
#MISE dir="{{cwd}}"
mise use python@latest
mise config set env._.python.venv.path .venvThe HTTP backend uses an intelligent caching system to optimize disk usage and installation speed. Instead of storing files separately for every tool, mise downloads and extracts files into a central cache directory. Tool installations are then created as symlinks to this cached content.
Downloaded and extracted files are stored in $MISE_CACHE_DIR/http-tarballs/. Default locations are:
~/.cache/mise/http-tarballs/~/Library/Caches/mise/http-tarballs/To ensure identical downloads are shared across different tools, cache keys are generated using:
strip_components option is included in the key because it changes the resulting directory structure.When a tool is installed via the HTTP backend, the installation directory is a symlink to the cached extracted content:
~/.local/share/mise/installs/http-my-tool/1.0.0 → ~/.cache/mise/http-tarballs/71f774.../extractedEach cache entry contains a metadata.json file describing the content:
{
"url": "https://example.com/releases/my-tool-v1.0.0.tar.gz",
"checksum": "sha256:a1b2c3d4e5f6789...",
"size": 1024000,
"extracted_at": 1703001234,
"platform": "macos-arm64"
}