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 Management

Name: pantheon-ai/mise-complete
Author: pantheon-ai

Configuration Commands

Viewing Configuration

# Show current configuration
mise config show

# Show as JSON
mise config show --json

# List all configuration files
mise config ls

# Show configuration from specific directory
mise config show -C /path/to/project

Validating Configuration

# Validate all configuration files
mise doctor

# Check specific config file
mise config validate mise.toml

# Debug configuration issues
mise config show --debug

Generating Configuration

# Generate mise.toml from existing version files
mise config generate

# Generate from .tool-versions
mise config generate .tool-versions > mise.toml

# Generate from .node-version, .python-version, etc.
mise config generate --all > mise.toml

Configuration Editing

Manual Editing

# Edit project config
$EDITOR mise.toml

# Edit global config
$EDITOR ~/.config/mise/config.toml

# Edit local overrides
$EDITOR mise.local.toml

Programmatic Updates

# Add a tool
echo 'node = "20"' >> mise.toml

# Update environment variable
mise set NODE_ENV=production

# Remove tool
mise unset tools.node

Configuration Templates

Starter Template

# mise.toml
[tools]
# Add your tools here
# node = "20"
# python = "3.11"

[env]
# Add your environment variables here
# NODE_ENV = "development"

[tasks.dev]
description = "Start development"
run = "echo 'Add your dev command here'"

[settings]
experimental = false

Full Template

# ==============================================================================
# Tools: Define runtime versions
# ==============================================================================
[tools]
node = "20"
python = "3.11"

# ==============================================================================
# Environment: Project environment variables
# ==============================================================================
[env]
NODE_ENV = "development"
PROJECT_ROOT = "{{ config_root }}"

# PATH additions
_.path = ["{{ config_root }}/bin"]

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

# ==============================================================================
# Tasks: Runnable commands
# ==============================================================================
[tasks.dev]
description = "Start development server"
run = "npm run dev"

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

[tasks.test]
description = "Run tests"
run = "npm test"

# ==============================================================================
# Settings: Mise behavior configuration
# ==============================================================================
[settings]
experimental = false
verbose = false

Configuration Migration

From asdf

# Convert .tool-versions to mise.toml
mise config generate .tool-versions > mise.toml

# Or migrate directly
mise install  # Mise reads .tool-versions automatically

Manual migration:

# .tool-versions
node 20.10.0
python 3.11.0

# mise.toml
[tools]
node = "20.10.0"
python = "3.11.0"

From direnv

# Old .envrc
export NODE_ENV=development
export API_URL=http://localhost:3000
PATH_add ./node_modules/.bin

# New mise.toml
[env]
NODE_ENV = "development"
API_URL = "http://localhost:3000"
_.path = ["./node_modules/.bin"]

From nvm/pyenv/rbenv

# .nvmrc
20.10.0

# .python-version
3.11.0

# .ruby-version
3.2.0

# mise.toml
[tools]
node = "20.10.0"
python = "3.11.0"
ruby = "3.2.0"

Configuration Backup

Backup Strategy

# Backup mise configuration
cp mise.toml mise.toml.backup

# Backup global config
cp ~/.config/mise/config.toml ~/.config/mise/config.toml.backup

# Backup entire mise directory
tar -czf mise-backup.tar.gz ~/.config/mise ~/.local/share/mise

Version Control

# .gitignore
mise.local.toml
.env.local
*.backup

# Commit mise.toml
git add mise.toml
git commit -m "Add mise configuration"

Configuration Sharing

Team Configuration

# mise.toml (shared with team)
[tools]
node = "20"
python = "3.11"

[env]
NODE_ENV = "development"

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

Setup for new team members:

git clone repo
cd repo
mise install  # Installs tools
mise trust    # Trust the configuration
mise run dev  # Start development

Personal Overrides

# mise.local.toml (personal, git-ignored)
[env]
DATABASE_URL = "postgresql://localhost/myapp_johndoe"
DEBUG = "true"

[settings]
verbose = true

Configuration Troubleshooting

Common Issues

Configuration not loading:

# Check which configs are being used
mise config ls

# Verify syntax
mise config validate

# Check environment
mise env

Tool versions not applying:

# Check tool installation
mise list

# Verify configuration
mise config show

# Reinstall tools
mise install

Environment variables not set:

# Check environment loading
mise env

# Verify activation
eval "$(mise activate bash)"

# Debug environment
mise env --debug

Debugging Commands

# Full system check
mise doctor

# Verbose output
mise --verbose config show

# Debug mode
mise --debug config show

# Trace execution
mise --trace config show

Configuration Security

Sensitive Data

# mise.toml (committed)
[env]
_.file = [".env", ".env.secrets"]

# .env.secrets (git-ignored)
API_SECRET=secret-key
DATABASE_PASSWORD=password

Trust System

# Trust project configuration
mise trust

# Trust specific config file
mise trust mise.toml

# List trusted configs
mise trust list

# Revoke trust
mise trust revoke

.gitignore Setup

# Mise local configuration
mise.local.toml

# Environment files
.env.local
.env.secrets
*.secret

# Backup files
*.backup
mise.toml.backup

Configuration Best Practices

Version Control mise.toml: Share tool versions with team
Ignore mise.local.toml: Keep personal settings private
Document Variables: Comment configuration sections
Validate Regularly: Run mise doctor frequently
Backup Before Changes: Keep backups of working configs
Use Templates: Start with starter templates
Separate Secrets: Never commit sensitive data
Trust Carefully: Only trust configurations you understand

Configuration Organization

Small Projects

project/
├── mise.toml            # All configuration
├── mise.local.toml      # Local overrides (git-ignored)
└── .env.local           # Secrets (git-ignored)

Medium Projects

project/
├── mise.toml            # Tools and environment
├── .mise/
│   └── tasks/           # Complex tasks
│       ├── deploy
│       ├── test
│       └── build
├── mise.local.toml      # Local overrides
└── .env.local           # Secrets

Large Projects (Monorepo)

project/
├── mise.toml            # Root configuration
├── .mise/
│   ├── config.toml     # Additional config
│   └── tasks/          # Shared tasks
├── packages/
│   ├── api/
│   │   └── mise.toml   # API-specific config
│   └── web/
│       └── mise.toml   # Web-specific config
└── mise.local.toml     # Root overrides

Configuration Anti-Patterns

❌ Don't: Commit Secrets

[env]
API_SECRET = "secret-key"

✅ Do: Use .env.local

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

❌ Don't: Duplicate Configuration

# In every package's mise.toml
[tools]
node = "20"
python = "3.11"

✅ Do: Use Root Configuration

# Root mise.toml
[tools]
node = "20"
python = "3.11"

# Packages inherit from root

❌ Don't: Hardcode Paths

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

✅ Do: Use Template Variables

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

❌ Don't: Mix Concerns

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

✅ Do: Group Related Items

[tools]
node = "20"

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

Install with Tessl CLI

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

references

config-anti-patterns.md

config-best-practices.md

tasks-organization.md

tasks-patterns.md

tools-installation.md