Idiomatic mise integration setup

[timothysparg]

I'm trying to configure a mise.toml so that cloning a project and running mise install results in a fully set up environment (tools + hk hooks installed).

My initial approach used a per-tool postinstall:

[tools]
hk = { version = "latest", postinstall = "hk install --mise" }
pkl = "latest"
actionlint = "latest"
yamlfmt = "latest"

[env]
HK_MISE = true

However, this led to intermittent CI failures. It appears postinstall runs per tool without guaranteed ordering, which caused a race condition where hk install --mise executed before dependencies like pkl were installed.

To avoid this, I switched to a global hook:

[tools]
hk = "latest"
actionlint = "latest"
yamlfmt = "latest"

[env]
HK_MISE = true

[hooks]
postinstall = "hk install --mise"

[settings]
experimental = true

This resolves the ordering issue, but relies on experimental hooks.

The other approach I come up with was to use mise exec in the postinstall

[tools]
hk = { version = "latest", postinstall = "mise exec pkl -- hk install --mise" }
pkl = "latest"
actionlint = "latest"
yamlfmt = "latest"

[env]
HK_MISE = true

This seems to work, but I saw some unexpected log entries

   mise hk@1.38.0                      ✓ running custom postinstall hook
-  mise WARN  Failed to resolve tool version list for tool: [MISE_TOOL_VERSION=1.38.0] tool@1.38.0: tool not found in mise tool registry
  Did you mean?
    aqua:kastenhq/external-tools/k10tools
    aqua:kool-dev/kool
    aqua:sachaos/toggl
    aqua:ianlewis/todos
    aqua:pacedotdev/oto
  mise pkl@0.31.0                       [1/2] install
  mise actionlint@1.7.11                [2/3] verify GitHub artifact attestations
  mise pkl@0.31.0                       [2/2] checksum pkl-linux-amd64
  mise pkl@0.31.0                       [2/2] extract pkl-linux-amd64
+  mise pkl@0.31.0                     ✓ installed
-  mise WARN  Failed to resolve tool version list for tool: [MISE_TOOL_VERSION=1.38.0] tool@1.38.0: tool not found in mise tool registry
  Did you mean?
    aqua:kastenhq/external-tools/k10tools
    aqua:kool-dev/kool
    aqua:sachaos/toggl
    aqua:ianlewis/todos
    aqua:pacedotdev/oto
-  mise WARN  missing: java@graalvm-community-25.0.2 uv@0.10.12 actionlint@1.7.11 yamlfm…
  mise uv@0.10.12                       [1/3] download uv-x86_64-unknown-linux-musl.tar.gz
  mise uv@0.10.12                       [2/3] verify GitHub artifact attestations
  mise java@graalvm-community-25.0.2    [1/3] checksum graalvm-community-jdk-25.0.2_linux-x64_bin.tar.gz
+  mise hk@1.38.0                        [3/3] Installed hk hook: /home/runner/work/mcp-server-rdf/mcp-server-rdf/.git/hooks/pre-commit
+  mise hk@1.38.0                        [3/3] Installed hk hook: /home/runner/work/mcp-server-rdf/mcp-server-rdf/.git/hooks/pre-push
+  mise hk@1.38.0                        [3/3] Installed hk hook: /home/runner/work/mcp-server-rdf/mcp-server-rdf/.git/hooks/commit-msg

I assume the warnings happen because of the "mise-ception" in some odd way?
I did try add --silent and --no-prepare to see if I could silence the warnings, but with not success.

Does this align with how mise + hk are meant to be used, or is there a cleaner pattern for ensuring everything is installed before running hk install --mise? Happy to help document it if so.

[jdx]

The recommended approach is to use the global [hooks] postinstall hook in mise.toml:

[tools]
hk = "latest"
pkl = "latest"
actionlint = "latest"
yamlfmt = "latest"

[env]
HK_MISE = true

[hooks]
postinstall = "hk install --mise"

[settings]
experimental = true

This is the cleanest option because [hooks] postinstall runs after all tools are installed, which avoids the race condition you hit with the per-tool postinstall.

The per-tool postinstall approach (mise exec pkl -- hk install --mise) works but has the downsides you noticed — the nested mise invocation produces warnings because of the MISE_TOOL_VERSION environment variable leaking into the inner mise exec call, causing it to try to resolve a tool named tool@1.38.0. Those warnings are harmless but noisy.

Regarding the experimental = true requirement — mise hooks have been around for a while now and are fairly stable. That said, if you want to avoid the experimental flag entirely, another approach is to simply have your CI run mise install && hk install --mise as two separate steps rather than relying on postinstall hooks at all.

For local developer setup, you could add a mise task:

[tasks.setup]
run = "hk install --mise"
description = "Install git hooks"

Then document mise install && mise run setup as the onboarding step.

This comment was generated by Claude Code.