tomevault-io mise Configuration as Single Source of Truth
Use mise [env] as centralized configuration with backward-compatible defaults.
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] section. Scripts read via environment variables with fallback defaults. Same code path works WITH or WITHOUT mise installed.
Key insight: mise auto-loads [env] values when shell has mise activate configured. Scripts using os.environ.get("VAR", "default") pattern work identically whether mise is present or not.
Quick Reference
Language Patterns
| Language | Pattern | Notes |
|---|---|---|
| Python | os.environ.get("VAR", "default") |
Returns string, cast if int |
| Bash | ${VAR:-default} |
Standard POSIX expansion |
| JavaScript | process.env.VAR || "default" |
Falsy check, watch for "0" |
| Go | os.Getenv("VAR") with default |
Empty string if unset |
| Rust | std::env::var("VAR").unwrap_or() |
Returns Result |
Special Directives
| Directive | Purpose | Example |
|---|---|---|
_.file |
Load from .env files | _.file = ".env" |
_.path |
Extend PATH | _.path = ["bin", "node_modules/.bin"] |
_.source |
Execute bash scripts | _.source = "./scripts/env.sh" |
_.python.venv |
Auto-create 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:
- Creates
.venvif it doesn't exist - Activates the venv automatically
- Works with
uvfor fast venv creation
Alternative via [settings]:
[settings]
python.uv_venv_auto = true
Hub-Spoke Architecture (CRITICAL)
Keep root mise.toml lean by delegating domain-specific tasks to subfolder mise.toml files. Applies to monorepos, ML/research projects, infrastructure, and data pipelines.
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.tomlapplies 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 workspaces, the venv is created at the workspace root. Dev dependencies should be hoisted to root pyproject.toml using [dependency-groups] (PEP 735).
Full guide: Monorepo Workspace Pattern
Template Syntax (Tera)
mise uses Tera templating. Delimiters: {{ }} expressions, {% %} statements, {# #} comments.
Built-in Variables
| Variable | Description |
|---|---|
{{config_root}} |
Directory containing .mise.toml |
{{cwd}} |
Current working directory |
{{env.VAR}} |
Environment variable |
{{mise_bin}} |
Path to mise binary |
{{mise_pid}} |
mise process ID |
{{xdg_cache_home}} |
XDG cache directory |
{{xdg_config_home}} |
XDG config directory |
{{xdg_data_home}} |
XDG data directory |
For functions (get_env, exec, arch, read_file, hash_file), filters (snakecase, trim, absolute), and conditionals: Code Patterns - Template Syntax
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 to access tool-generated paths:
[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
- Identify hardcoded values - timeouts, paths, thresholds, feature flags
- Create
.mise.toml- add[env]section with documented variables - Add venv auto-creation -
_.python.venv = { path = ".venv", create = true } - Update scripts - use env vars with original values as defaults
- Add ADR reference - comment:
# ADR: 2025-12-08-mise-env-centralized-config - Test without mise - verify script works using defaults
- Test with mise - verify activated shell uses
.mise.tomlvalues
GitHub Token Multi-Account Patterns {#github-token-multi-account-patterns}
For multi-account GitHub setups, mise [env] provides per-directory token configuration that overrides gh CLI's global authentication.
Rule: Always set BOTH GH_TOKEN and GITHUB_TOKEN pointing to the same token file.
| Variable | Usage Context |
|---|---|
GH_TOKEN |
mise [env], Doppler, verification tasks |
GITHUB_TOKEN |
npm scripts, GitHub Actions, semantic-release |
Full guide with templates, verification, and 1Password integration: GitHub Token Patterns
Anti-Patterns
| Anti-Pattern | Why | Instead |
|---|---|---|
mise exec -- script.py |
Forces mise dependency | Use env vars with defaults |
Secrets in .mise.toml |
Visible in repo | Use Doppler or redact = true |
| No defaults in scripts | Breaks without mise | Always provide fallback |
[env] secrets for pueue jobs |
Pueue runs clean shell, no mise | Use python-dotenv + .env file |
__MISE_DIFF leaks via SSH |
Remote trust errors | unset __MISE_DIFF before SSH |
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 skill for task definitions with dependency management.
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.tomltemplate - 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 in your project.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Env vars not loading | mise not activated | Add mise activate to shell rc file |
| Venv not created | Python not installed | Run mise install python |
| Tasks not found | Wrong mise.toml location | Ensure mise.toml is in project root |
| PATH not updated | Shims not in PATH | Add mise shims to ~/.zshenv |
| .file not loading | .env file missing | Create .env file or remove .file directive |
| Subfolder config ignored | Missing min_version | Add min_version to subfolder mise.toml |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- 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.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.