mise Configuration as Single Source of Truth

Use mise

[env]

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

• Centralizing environment variables in mise.toml
• Setting up Python venv auto-creation with mise
• Implementing hub-spoke configuration for monorepos
• Creating backward-compatible environment patterns

Core Principle

Define all configurable values in

.mise.toml

[env]

Key insight: mise auto-loads

[env]

mise activate

os.environ.get("VAR", "default")

Quick Reference

Language Patterns

os.environ.get("VAR", "default")

${VAR:-default}

process.env.VAR || "default"

os.Getenv("VAR")

std::env::var("VAR").unwrap_or()

Special Directives

_.file

_.file = ".env"

_.path

_.path = ["bin", "node_modules/.bin"]

_.source

_.source = "./scripts/env.sh"

_.python.venv

_.python.venv = { path = ".venv", create = true }

For detailed directive examples with options (redact, tools, multi-file): Code Patterns

Python Venv Auto-Creation (Critical)

Auto-create and activate Python virtual environments:

[env]
_.python.venv = { path = ".venv", create = true }

This pattern is used in ALL projects. When entering the directory with mise activated:

1. Creates

   .venv

   if it doesn't exist
2. Activates the venv automatically
3. Works with

   uv

   for fast venv creation

Alternative via [settings]:

[settings]
python.uv_venv_auto = true

Hub-Spoke Architecture (CRITICAL)

Keep root

mise.toml

mise.toml

Key rules:

• Hub owns

  [tools]

  and orchestration tasks
• Spokes inherit hub's

  [tools]

  automatically
• Spoke

  [env]

  extends hub's

  [env]

  (can override per domain)

• .mise.local.toml

  applies at directory level (secrets stay local)

Full guide with directory structures, examples, and anti-patterns: Hub-Spoke Architecture

Wiki Reference: Pattern-mise-Configuration

Monorepo Workspace Pattern

For Python monorepos using

uv

pyproject.toml

[dependency-groups]

Full guide: Monorepo Workspace Pattern

Template Syntax (Tera)

mise uses Tera templating. Delimiters:

{{ }}

{% %}

{# #}

Built-in Variables

{{config_root}}

{{cwd}}

{{env.VAR}}

{{mise_bin}}

{{mise_pid}}

{{xdg_cache_home}}

{{xdg_config_home}}

{{xdg_data_home}}

For functions (

get_env

exec

arch

read_file

hash_file

snakecase

trim

absolute

Required & Redacted Variables

[env]
# Required - fails if not set
DATABASE_URL = { required = true }
API_KEY = { required = "Get from https://example.com/api-keys" }

# Redacted - hides from output
SECRET = { value = "my_secret", redact = true }
_.file = { path = ".env.secrets", redact = true }

# Pattern-based redactions
redactions = ["*_TOKEN", "*_KEY", "PASSWORD"]

For combined patterns and detailed examples: Code Patterns - Required & Redacted

Lazy Evaluation (

tools = true

)

By default, env vars resolve BEFORE tools install. Use

tools = true

[env]
GEM_BIN = { value = "{{env.GEM_HOME}}/bin", tools = true }
_.file = { path = ".env", tools = true }

[settings] and [tools]

[settings]
experimental = true
python.uv_venv_auto = true

[tools]
python = "<version>"
node = "latest"
uv = "latest"
rust = { version = "<version>", profile = "minimal" }

# SSoT-OK: mise min_version directive, not a package version
min_version = "2024.9.5"

For full settings reference and version pinning options: Code Patterns - Settings & Tools

Implementation Steps

1. Identify hardcoded values - timeouts, paths, thresholds, feature flags
2. Create

   .mise.toml

   - add

   [env]

   section with documented variables
3. Add venv auto-creation -

   _.python.venv = { path = ".venv", create = true }

4. Update scripts - use env vars with original values as defaults
5. Add ADR reference - comment:

   # ADR: 2025-12-08-mise-env-centralized-config

6. Test without mise - verify script works using defaults
7. Test with mise - verify activated shell uses

   .mise.toml

   values

GitHub Token Multi-Account Patterns {#github-token-multi-account-patterns}

For multi-account GitHub setups, mise

[env]

Rule: Always set BOTH

GH_TOKEN

GITHUB_TOKEN

GH_TOKEN

GITHUB_TOKEN

Full guide with templates, verification, and 1Password integration: GitHub Token Patterns

Anti-Patterns

mise exec -- script.py

.mise.toml

redact = true

[env]

python-dotenv

.env

__MISE_DIFF

unset __MISE_DIFF

Critical detail on non-interactive shell secrets: Anti-Patterns Guide

Task Orchestration Integration

When detecting multi-step project workflows during mise configuration, invoke the

mise-tasks

Detection triggers: multi-step workflows, repeatable commands, dependency chains, file-tracked builds.

Full guide with examples: Task Orchestration | mise-tasks skill

Additional Resources

• Code Patterns & Templates - Complete code examples for Python, Bash, JS, Go, Rust, and full

  .mise.toml

  template
• Hub-Spoke Architecture - Directory structures, hub/spoke responsibilities, inheritance rules
• GitHub Token Patterns - Multi-account setup, verification, 1Password integration
• Anti-Patterns Guide - Non-interactive shell secrets, pueue/cron/systemd gotchas
• Task Orchestration - Workflow detection triggers, environment-to-tasks example
• Monorepo Workspace - uv workspaces, hoisted dev dependencies (PEP 735)
• Wiki: Pattern-mise-Configuration

ADR Reference: When implementing mise configuration, create an ADR at

docs/adr/YYYY-MM-DD-mise-env-centralized-config.md

Troubleshooting

mise install python

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.