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

Environment Variable Loading

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

Activation Methods

Automatic Shell Integration

Enable automatic environment loading when entering directories:

# Add to ~/.bashrc, ~/.zshrc, etc.
eval "$(mise activate bash)"  # or zsh, fish

When you cd into a directory with mise.toml, environment variables are automatically loaded.

Manual Activation

# Load environment in current shell
eval "$(mise env)"

# Load environment for specific shell
eval "$(mise env -s zsh)"

Running Commands with Environment

# Run command with mise environment
mise exec -- npm start

# Short form
mise x -- node app.js

# Run task (automatically includes environment)
mise run dev

Checking Current Environment

# Show all mise-managed environment variables
mise env

# Show specific variable
mise env | grep NODE_ENV

# Show environment for specific directory
mise env -C /path/to/project

Loading Order

Environment variables are loaded in this order (later overrides earlier):

Global config (~/.config/mise/config.toml)
Project config (mise.toml)
Local config (mise.local.toml)
Environment files (.env, .env.local)
Shell environment (existing variables)

Example Loading Sequence

# ~/.config/mise/config.toml
[env]
EDITOR = "vim"
NODE_ENV = "development"

# project/mise.toml
[env]
NODE_ENV = "production"  # Overrides global
API_URL = "https://api.example.com"

# project/mise.local.toml
[env]
API_URL = "http://localhost:3000"  # Overrides project
DEBUG = "true"

Result:

EDITOR = "vim" (from global)
NODE_ENV = "production" (from project, overrides global)
API_URL = "http://localhost:3000" (from local, overrides project)
DEBUG = "true" (from local)

Environment File Loading

Basic .env Loading

[env]
_.file = ".env"

# .env
NODE_ENV=development
API_URL=http://localhost:3000
DATABASE_URL=postgresql://localhost/myapp

Multiple File Loading

[env]
_.file = [
  ".env",              # Base configuration
  ".env.local",        # Local overrides
  ".env.{{ env.NODE_ENV }}"  # Environment-specific
]

Load order: .env → .env.local → .env.development

Conditional Loading

[env]
NODE_ENV = "development"

# This will load .env.development
_.file = ".env.{{ env.NODE_ENV }}"

Optional File Loading

# Mise ignores missing files by default
# These won't error if files don't exist
[env]
_.file = [".env", ".env.local"]

Tool Environment Activation

Python Virtual Environments

[tools]
python = "3.11"

[env]
VIRTUAL_ENV = "{{ config_root }}/.venv"
_.path = ["{{ config_root }}/.venv/bin"]

# Automatically activates venv when entering directory
cd my-project
which python  # Points to .venv/bin/python

Node.js Environment

[tools]
node = "20"

[env]
NODE_ENV = "development"
_.path = ["{{ config_root }}/node_modules/.bin"]

cd my-project
which eslint  # Points to node_modules/.bin/eslint

Go Environment

[tools]
go = "1.21"

[env]
GOPATH = "{{ config_root }}/.go"
_.path = ["{{ config_root }}/.go/bin"]

Rust Environment

[tools]
rust = "stable"

[env]
CARGO_HOME = "{{ config_root }}/.cargo"
_.path = ["{{ config_root }}/.cargo/bin"]

Replacing direnv

Mise can fully replace direnv with more features:

direnv .envrc

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

Mise Equivalent

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

Migration from direnv

Remove .envrc files
Create mise.toml with equivalent configuration
Replace direnv allow with automatic mise activation
Use mise trust if needed for project config

Debugging Environment Loading

Check Loaded Variables

# Show all mise environment variables
mise env

# Show as export statements
mise env -s bash

# Check specific variable
mise env | grep DATABASE_URL

Verify Loading Order

# Show which config files are loaded
mise config ls

# Show environment from specific config
mise env -C /path/to/project

Troubleshooting

# Check for syntax errors in mise.toml
mise doctor

# Validate environment configuration
mise env --json

# See which files would be loaded
mise config ls

Performance Optimization

Lazy Loading

Environment variables are loaded lazily - only when needed:

# Fast - doesn't load environment
cd project

# Loads environment only when needed
npm start  # Environment loaded here

Caching

Mise caches environment calculations:

# First load - slower
cd project && mise env

# Subsequent loads - faster (cached)
cd project && mise env

Clear Cache

# Clear environment cache
mise cache clear

Shell-Specific Features

Bash/Zsh Completion

# Enable completion for environment variables
eval "$(mise activate bash)"

# Tab completion works for mise-managed vars
echo $NODE_<TAB>

Fish Shell

# ~/.config/fish/config.fish
mise activate fish | source

Nushell

# ~/.config/nushell/config.nu
mise activate nu

Common Patterns

Development vs Production

[env]
NODE_ENV = "development"
_.file = ".env.{{ env.NODE_ENV }}"

# Loads .env.development in dev
# Loads .env.production in prod

CI/CD Integration

# In CI pipeline
mise install  # Install tools
mise exec -- npm test  # Run with environment

Docker Integration

# Dockerfile
FROM node:20
WORKDIR /app

# Install mise
RUN curl https://mise.run | sh
ENV PATH="/root/.local/bin:$PATH"

# Copy config and install tools
COPY mise.toml .
RUN mise install

# Use mise to run application
CMD ["mise", "exec", "--", "npm", "start"]

Best Practices

Use Shell Integration: Enable mise activate for automatic loading
Prefer mise exec: Use mise exec over manual env loading
Check Variables: Use mise env to verify loaded variables
Cache Awareness: Clear cache if environment seems stale
Trust Projects: Use mise trust for known projects

Anti-Patterns

❌ Don't: Mix Environment Managers

# Don't mix direnv and mise
eval "$(direnv hook bash)"
eval "$(mise activate bash)"

✅ Do: Use One Manager

# Use mise exclusively
eval "$(mise activate bash)"

❌ Don't: Override Mise Variables

# Don't override mise-managed variables
export NODE_ENV=production  # Conflicts with mise

✅ Do: Configure in mise.toml

[env]
NODE_ENV = "production"

❌ Don't: Source .env Manually

# Don't manually source files
source .env

✅ Do: Let Mise Handle It

[env]
_.file = ".env"

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