Blog Docs Log in Get started

pantheon-ai/mise-complete

Configure and operate Mise for deterministic developer environments. Use when installing runtime/tool versions, defining reusable tasks, managing layered environment variables, migrating from asdf/nvm/pyenv, or debugging mise.toml behavior in CI and local shells. Keywords: mise, mise.toml, tool versions, tasks, env, asdf migration, setup automation, dev environment.

Overall
score

99%

Review — 99%

Does it follow best practices?

Validation — 10 / 11 Passed

Validation for skill structure

Configuration File Structure

mise.toml Overview

The mise.toml file is the main configuration file for Mise, using TOML format.

Basic Structure

# Tool versions
[tools]
node = "20"
python = "3.11"
rust = "stable"

# Environment variables
[env]
NODE_ENV = "development"
API_URL = "http://localhost:3000"

# Tasks
[tasks.build]
description = "Build the project"
run = "npm run build"

# Settings
[settings]
experimental = true

Configuration Sections

[tools]

Specifies tool versions to install and manage:

[tools]
node = "20.10.0"
python = "3.11"
terraform = "1.6"
kubectl = "latest"

Supported formats:

Exact version: "20.10.0"
Major.minor: "20.10"
Major only: "20"
Version prefix: "prefix:20.10.0"
Latest: "latest"
Path: "path:./custom-node"

[env]

Defines environment variables:

[env]
NODE_ENV = "development"
DATABASE_URL = "postgresql://localhost/myapp"
_.path = ["./bin", "./node_modules/.bin"]
_.file = [".env", ".env.local"]

Special keys:

_.path: Adds directories to PATH
_.file: Loads environment from files
_.source: Sources shell scripts

[tasks.*]

Defines executable tasks:

[tasks.dev]
description = "Start development server"
run = "npm run dev"

[tasks.test]
description = "Run tests"
depends = ["lint"]
run = [
  "npm run test:unit",
  "npm run test:integration"
]

Task properties:

description: Human-readable description
run: Command(s) to execute
depends: Task dependencies
env: Task-specific environment
dir: Working directory
sources: Input files
outputs: Generated files
alias: Alternative names

[settings]

Mise behavior configuration:

[settings]
experimental = true
verbose = false
jobs = 4

Configuration Files

Project Configuration

mise.toml (committed):

[tools]
node = "20"

[env]
NODE_ENV = "development"

[tasks.dev]
run = "npm run dev"

mise.local.toml (git-ignored):

[env]
DATABASE_URL = "postgresql://localhost/myapp_johndoe"
DEBUG = "true"

Global Configuration

~/.config/mise/config.toml:

[settings]
experimental = true

[env]
EDITOR = "code"
_.path = ["$HOME/.local/bin"]

[tools]
# Global tools available everywhere

System Configuration

/etc/mise/config.toml:

[env]
CORPORATE_PROXY = "http://proxy.company.com:8080"

File Locations

Search Order

Mise searches for configuration files in this order:

./mise.local.toml (current directory)
./mise.toml (current directory)
../.mise.toml (parent directory)
~/.config/mise/config.toml (global)
/etc/mise/config.toml (system)

Explicit Paths

# Use specific config file
mise --config /path/to/config.toml run build

# Use config from directory
mise -C /path/to/project run test

Tool Configuration

Version Specification

[tools]
# Exact version
node = "20.10.0"

# Version range
python = "3.11"

# Latest
rust = "latest"

# Version prefix
ruby = "ref:main"

# Path to local installation
go = "path:$HOME/custom-go"

# System installation
java = "system"

Tool-Specific Options

[tools]
node = { version = "20", install_args = "--with-intl=full" }
python = { version = "3.11", virtualenv = ".venv" }

Multiple Versions

[tools]
node = ["18", "20", "21"]  # Install multiple versions

Environment Configuration

Variable Definition

[env]
# Simple values
NODE_ENV = "development"
PORT = "3000"

# Multi-line values
PRIVATE_KEY = """
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
"""

# Template variables
PROJECT_ROOT = "{{ config_root }}"
DATA_DIR = "{{ config_root }}/data"

PATH Management

[env]
_.path = [
  "{{ config_root }}/bin",
  "{{ config_root }}/node_modules/.bin",
  "$HOME/.local/bin"
]

File Loading

[env]
_.file = [
  ".env",
  ".env.local",
  ".env.{{ env.NODE_ENV }}"
]

Script Sourcing

[env]
_.source = "scripts/env-setup.sh"

Task Configuration

Inline Tasks

[tasks.build]
description = "Build the project"
run = "npm run build"

[tasks.test]
description = "Run tests"
depends = ["build"]
run = [
  "npm run lint",
  "npm test"
]

Task Properties

[tasks.deploy]
description = "Deploy to production"
depends = ["test", "build"]
run = "./scripts/deploy.sh"
dir = "{{ config_root }}"
env = { ENVIRONMENT = "production" }
sources = ["src/**/*", "package.json"]
outputs = ["dist/**/*"]
alias = "ship"

File-Based Tasks

# Tasks can also be defined in .mise/tasks/
# mise.toml can reference them
[tasks]
# No inline definition needed if file exists

Settings Configuration

Common Settings

[settings]
# Enable experimental features
experimental = true

# Verbose output
verbose = false

# Number of parallel jobs
jobs = 4

# Disable telemetry
telemetry = false

# Automatic activation
activate_aggressive = true

# Legacy version file support
legacy_version_file = true

# Always keep downloads
always_keep_download = false

# Plugin autoupdate
plugin_autoupdate_last_check_duration = "7d"

Task Settings

[settings]
task_output = "prefix"  # or "interleave"
raw = false

Configuration Validation

Syntax Check

# Validate configuration
mise doctor

# Show parsed configuration
mise config show

# List configuration files
mise config ls

Common Issues

Invalid TOML syntax:

[env]
KEY = value  # Missing quotes

Correct:

[env]
KEY = "value"

Comments

# This is a comment
[tools]
node = "20"  # Inline comment

# Multi-line comment block
# explaining the configuration
[env]
API_URL = "http://localhost:3000"

Best Practices

Commit mise.toml: Share tool versions and tasks with team
Ignore mise.local.toml: Personal overrides stay local
Document Sections: Add comments explaining configuration
Group Related Items: Organize by purpose
Use Templates: Leverage {{ config_root }} for paths
Validate Regularly: Run mise doctor to check configuration

Example Complete Configuration

# Project: My Application
# Description: Web application with Node.js and PostgreSQL

# ==============================================================================
# Tool Versions
# ==============================================================================
[tools]
node = "20.10.0"
terraform = "1.6"
kubectl = "latest"

# ==============================================================================
# Environment Variables
# ==============================================================================
[env]
# Application
NODE_ENV = "development"
PORT = "3000"
LOG_LEVEL = "debug"

# Database
DATABASE_URL = "postgresql://localhost/myapp_dev"

# Paths
PROJECT_ROOT = "{{ config_root }}"
_.path = [
  "{{ config_root }}/bin",
  "{{ config_root }}/node_modules/.bin"
]

# Load additional environment files
_.file = [".env", ".env.local"]

# ==============================================================================
# Development Tasks
# ==============================================================================
[tasks.dev]
description = "Start development server"
run = "npm run dev"

[tasks.build]
description = "Build for production"
run = "npm run build"

[tasks.test]
description = "Run all tests"
depends = ["lint"]
run = [
  "npm run test:unit",
  "npm run test:integration"
]

[tasks.lint]
description = "Lint code"
run = "eslint ."

# ==============================================================================
# Deployment Tasks
# ==============================================================================
[tasks.deploy]
description = "Deploy to production"
depends = ["test", "build"]
run = "./scripts/deploy.sh"
env = { ENVIRONMENT = "production" }

# ==============================================================================
# Settings
# ==============================================================================
[settings]
experimental = true
verbose = false
jobs = 4

Anti-Patterns

❌ Don't: Mix Configuration Concerns

[env]
NODE_ENV = "development"
[tools]
node = "20"
[env]
PORT = "3000"

✅ Do: Group Related Configuration

[tools]
node = "20"

[env]
NODE_ENV = "development"
PORT = "3000"

❌ Don't: Hardcode Paths

[env]
DATA_DIR = "/Users/john/projects/myapp/data"

✅ Do: Use Template Variables

[env]
DATA_DIR = "{{ config_root }}/data"

❌ Don't: Commit Secrets

[env]
API_SECRET = "super-secret-key"

✅ Do: Use .env.local

[env]
_.file = [".env", ".env.local"]

Install with Tessl CLI

npx tessl i pantheon-ai/mise-complete@0.1.0

references

config-anti-patterns.md

config-best-practices.md

config-management.md

config-structure.md

env-definition.md

env-hierarchies.md

env-patterns.md

tasks-definition.md

tasks-execution.md

tasks-organization.md

tasks-patterns.md

tools-installation.md

tools-migration.md

tools-plugins.md

tools-versions.md