Repository: jdx/mise

Stars: 26799

CLAUDE.md Copy Chapter

Repository Agent Guide

This file provides guidance to AI coding agents when working with code in this repository. It keeps the CLAUDE.md filename for compatibility with existing tooling, and AGENTS.md symlinks to it for other agents.

Development Commands Copy Chapter

Building and Testing Copy Section

Debugging Copy Section

Code Quality and Testing Copy Section

Documentation and Generation Copy Section

Development Copy Section

Code Architecture Copy Chapter

High-Level Structure Copy Section

Core Components:
- src/main.rs - Entry point and CLI initialization
- src/cli/ - Command-line interface implementation with subcommands
- src/config/ - Configuration file parsing and management
- src/backend/ - Tool backend implementations (asdf, vfox, cargo, npm, etc.)
- src/toolset/ - Tool version management and installation logic
- src/task/ - Task execution system
- src/plugins/ - Plugin system for extending tool support

Key Backend Systems:
- src/backend/asdf.rs - ASDF plugin compatibility
- src/backend/vfox.rs - VersionFox plugin system
- src/backend/cargo.rs - Rust Cargo tool backend
- src/backend/npm.rs - Node.js/npm tool backend
- src/backend/github.rs - GitHub releases backend
- src/backend/aqua.rs - Aqua tool registry integration

Core Tools (Built-in):
- src/plugins/core/ - Built-in tool implementations (Node, Python, Go, Ruby, etc.)

Configuration System:
- mise.toml files for project configuration
- .tool-versions files for ASDF compatibility
- Environment variable management and templating
- Task definition and execution

Key Design Patterns Copy Section

Configuration Files Copy Section

Test Structure Copy Section

Build System Copy Section

Development Guidelines Copy Chapter

Conventional Commits (REQUIRED) Copy Section

Format: <type>(<scope>): <description>

Types:
- feat: - New features
- fix: - Bug fixes that affect the CLI behavior (not CI, docs, or infrastructure)
- refactor: - Code refactoring
- docs: - Documentation changes
- style: - Code style/formatting (no logic changes)
- perf: - Performance improvements
- test: - Testing changes
- chore: - Maintenance tasks, releases, dependency updates, CI/infrastructure changes
- security: - Security-related changes
- registry: - Any changes to registry/ (no scope needed, use for both new tools and fixes)

Scopes:
- For command-specific changes, use the command name: install, activate, use, exec, etc.
- For subsystem changes: config, backend, env, task, vfox, python, github, release, completions, http, schema, doctor, shim, core, deps, ci
- Use task (not run) for task-related changes, even if the code lives in src/cli/run.rs or src/cmd.rs

Description Style:
- Use lowercase after the colon
- Use imperative mood ("add feature" not "added feature")
- Keep it concise but descriptive

Examples:
- fix(install): resolve version mismatch for previously installed tools
- feat(activate): add fish shell support
- feat(vfox): add semver Lua module for version sorting
- feat(env): add environment caching with module cacheability support
- docs(contributing): update hk usages
- chore: release 2026.1.6
- chore(ci): add FORGEJO_TOKEN for API authentication
- registry: add miller

Pre-commit Process Copy Section

Deprecation Policy Copy Chapter

When deprecating a feature or backend:

1. Immediately: Mark as deprecated in docs (add warning banner)
2. 6 months later (warn_at): Display deprecation warning in CLI using deprecated_at! macro from src/output.rs
3. 12 months after warn (remove_at): debug_assert! in deprecated_at! fires, signaling the code should be removed

Use mise version format for dates (e.g., deprecated_at!("2026.10.0", "2027.10.0", "id", "message")).

If the replacement has been available for a long time, the CLI warning can start immediately (set warn_at to the current version).

Important Implementation Notes Copy Chapter

Backend System Copy Section

Plugin Development Copy Section

Configuration Parsing Copy Section

Testing Strategy Copy Section

Cross-Platform Considerations Copy Section

GitHub Interactions Copy Chapter

When posting comments on GitHub PRs or discussions, always include a note that the comment was AI-generated (e.g., "This comment was generated by an AI coding assistant.").

Documentation Copy Chapter

URL Structure Copy Section

- Dev tools & backends: mise.jdx.dev/dev-tools/backends/<backend>.html (e.g., mise.jdx.dev/dev-tools/backends/s3.html)
- Configuration: mise.jdx.dev/configuration/...
- Tasks: mise.jdx.dev/tasks/...
- Environments: mise.jdx.dev/environments/...
- CLI reference: mise.jdx.dev/cli/...

Do NOT use shortened paths like mise.jdx.dev/backends/... - always include the full path matching the docs/ directory structure.

README.md Copy Chapter

<div align="center">

<h1 align="center">
<a href="https://mise.jdx.dev">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/public/logo-dark.svg" />
<img src="docs/public/logo-light.svg" alt="mise" width="256" height="256" />
</picture>
<br>
mise-en-place
</a>
</h1>

<p>
<a href="https://crates.io/crates/mise"><img alt="Crates.io" src="https://img.shields.io/crates/v/mise?style=for-the-badge&color=8B2252"></a>
<a href="https://github.com/jdx/mise/blob/main/LICENSE"><img alt="GitHub" src="https://img.shields.io/github/license/jdx/mise?style=for-the-badge&color=6B7F4E"></a>
<a href="https://github.com/jdx/mise/actions/workflows/test.yml"><img alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/jdx/mise/test.yml?style=for-the-badge&color=C5975B"></a>
<a href="https://discord.gg/mABnUDvP57"><img alt="Discord" src="https://img.shields.io/discord/1066429325269794907?style=for-the-badge&color=8B2252"></a>
</p>

<p><b>The front-end to your dev env</b></p>

<p align="center">
<a href="https://mise.jdx.dev/getting-started.html">Getting Started</a> •
<a href="https://mise.jdx.dev">Documentation</a> •
<a href="https://mise.jdx.dev/dev-tools/">Dev Tools</a> •
<a href="https://mise.jdx.dev/environments/">Environments</a> •
<a href="https://mise.jdx.dev/tasks/">Tasks</a>
</p>

<hr />

</div>

What is it? Copy Chapter

- Like asdf (or nvm or pyenv but for any language) it manages dev tools like node, python, cmake, terraform, and hundreds more.
- Like direnv it manages environment variables for different project directories.
- Like make it manages tasks used to build and test projects.

Demo Copy Chapter

The following demo shows how to install and use mise to manage multiple versions of node on the same system.
Note that calling which node gives us a real path to node, not a shim.

It also shows that you can use mise to install and many other tools such as jq, terraform, or go.


See demo transcript.

Quickstart Copy Chapter

Install mise Copy Section

See Getting started for more options.

$ curl https://mise.run | sh
$ ~/.local/bin/mise --version
              _                                        __
   ____ ___  (_)_______        ___  ____        ____  / /___ _________
  / __ __ \/ / ___/ _ \______/ _ \/ __ \______/ __ \/ / __ / ___/ _ \
 / / / / / / (__  )  __/_____/  __/ / / /_____/ /_/ / / /_/ / /__/  __/
/_/ /_/ /_/_/____/\___/      \___/_/ /_/     / .___/_/\__,_/\___/\___/
                                            /_/                 by @jdx
2026.4.16 macos-arm64 (2026-04-17)

Hook mise into your shell (pick the right one for your shell):

note this assumes mise is located at ~/.local/bin/mise

which is what https://mise.run does by default

echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish
echo '~/.local/bin/mise activate pwsh | Out-String | Invoke-Expression' >> ~/.config/powershell/Microsoft.PowerShell_profile.ps1

Execute commands with specific tools Copy Section

$ mise exec node@26 -- node -v
mise [email protected] ✓ installed
v26.x.x

Install tools Copy Section

$ mise use --global node@26 go@1
$ node -v
v26.x.x
$ go version
go version go1.x.x macos/arm64

See dev tools for more examples.

Manage environment variables Copy Section

mise.toml

[env]
SOME_VAR = "foo"

$ mise set SOME_VAR=bar
$ echo $SOME_VAR
bar

Note that mise can also load .env files.

Run tasks Copy Section

mise.toml

[tasks.build]
description = "build the project"
run = "echo building..."

$ mise run build
building...

See tasks for more information.

Example mise project Copy Section

Here is a combined example to give you an idea of how you can use mise to manage your a project's tools, environment, and tasks.

mise.toml

[tools]
terraform = "1"
aws-cli = "2"
[env]
TF_WORKSPACE = "development"
AWS_REGION = "us-west-2"
AWS_PROFILE = "dev"
[tasks.plan]
description = "Run terraform plan with configured workspace"
run = """
terraform init
terraform workspace select $TF_WORKSPACE
terraform plan
"""
[tasks.validate]
description = "Validate AWS credentials and terraform config"
run = """
aws sts get-caller-identity
terraform validate
"""
[tasks.deploy]
description = "Deploy infrastructure after validation"
depends = ["validate", "plan"]
run = "terraform apply -auto-approve"

Run it with:

mise install # install tools specified in mise.toml
mise run deploy

Find more examples in the mise cookbook.

Full Documentation Copy Chapter

See mise.jdx.dev

GitHub Issues & Discussions Copy Chapter

Due to the volume of issue submissions mise received, using GitHub Issues became unsustainable for
the project. Instead, mise uses GitHub Discussions which provide a more community-centric platform
for communication and require less management on the part of the maintainers.

Please note the following discussion categories, which match how issues are often used:

- Announcements
- Ideas: for feature requests, etc.
- Troubleshooting & Bug Reports

Special Thanks Copy Chapter

We're grateful for Cloudflare's support through Project Alexandria.

Contributors Copy Chapter