jdx Release Notes

This release introduces selective profile inheritance, letting profiles compose their secrets, providers, and lease backends from other named profiles, alongside a batch of correctness fixes to secret resolution, sync caching, and the background daemon.

Added

• Selective profile inheritance (#770) -- @jdx. Named profiles can now declare an ordered inherits list so their configuration is layered from ancestor profiles before the profile itself, with later entries winning on conflicts. Inheritance applies to secrets, providers, lease backends, and default_provider, and supports nested inheritance. Unknown inherited profiles and inheritance cycles are reported as actionable configuration errors, and inherited fnox.<profile>.toml files are discovered automatically.

  [profiles.openai.secrets]
  OPENAI_API_KEY = { provider = "age", value = "encrypted-key..." }
  
  [profiles.database-local.secrets]
  DATABASE_PASSWORD = { provider = "age", value = "encrypted-password..." }
  
  [profiles.api-local]
  inherits = ["openai", "database-local"]
  

  fnox -P api-local exec -- ./api
  

Fixed …

This release expands bootstrap system setup with firewall rate limiting and more systemd directives, adds a scoped locked mode for mixing distribution and user tool policies, and fixes lazy tools so they install when invoked from tasks and mise x.

Added

• bootstrap: New action = "limit" for incoming TCP firewall rules rate-limits connections per source. It maps to UFW's native limiting and bounded per-source IPv4/IPv6 nftables meters; firewalld fails closed since it cannot express safe per-source limiting. Limit rules are treated as preserving SSH access by the lockout guard. (#12669 by @jdx)

• bootstrap: Bootstrap systemd units now support requires (Requires=), repeatable environment_file (EnvironmentFile=), nice, and umask, with validation for nice ranges (-20 to 19) and octal umasks. Note that requires does not imply ordering; use after for that. (#12683 by @jdx)

• config: New global-only locked_scopes setting (also MISE_LOCKED_SCOPES) lets you scope locked mode to specific config sources, so a distribution can ship rolling or lazy tools through /etc/mise/config.toml without forcing users to maintain a system lockfile. Defaults to all three scopes to preserve existing behavior. (#12667 by @jdx)

  [settings]
  locked_scopes = ["project", "global"]
  

Fixed …

This release introduces lazy tool shims, which install a tool automatically the first time one of its commands is invoked, plus an opt-in Erlang precompiled OS override and a fix for nested mise calls during postinstall hooks.

Added

• tools: Declare a tool as lazy in [tools] with lazy = true and mise generates bootstrap shims into its normal user/system shim farms. The provider is installed only when one of its commands is first called, then executes immediately; subsequent calls run the real binary without another mise dispatch. Registry tools derive their command names from registry bins, while explicit or non-registry backends declare them with lazy_bins. A bare mise install skips lazy declarations; use mise install --include-lazy to provision them all. New global path settings (shims_dir/MISE_SHIMS_DIR, system_installs_dir/MISE_SYSTEM_INSTALLS_DIR, system_shims_dir/MISE_SYSTEM_SHIMS_DIR) and mise reshim --system support system-scoped and collocated layouts. (#12594 by @jdx)

  [tools]
  node = { version = "24", lazy = true }
  "github:example/acme" = { version = "1.2.3", lazy = true, lazy_bins = ["acme", "acmectl"] }
  ``` …
  

This release adds configurable command wrappers for intercepting ordinary commands, alongside a batch of shell and PATH fixes that make Windows activation more reliable and clearer upgrade and error messaging.

Added

• shims: New [wrappers] config lets you intercept an ordinary command name with a different command, arguments, and environment. Wrappers take precedence over mise-managed tools, and mise strips its dispatch directories before delegating so the underlying tool still resolves from mise or the system. Works with normal activation, activate --shims, and mise exec; managed wrapper shims are refreshed by mise reshim. (#12617 by @jdx)

  [tools]
  mr-boxington = "1.1.0"
  
  [wrappers.cargo]
  command = "mbx"
  env = { MBX_CARGO_SHIM_MODE = "1" }
  

Fixed

• elvish: mise env and mise activate --shims now emit valid Elvish quoting instead of bash's. This fixes several corruptions that mostly surfaced on Windows: stray quotes and the wrong PATH separator in activate --shims, apostrophes and ! arriving with backslashes, and \n sequences in paths like C:\nodejs being turned into newlines. (#12584 by @JamBalaya56562) …

This release seeds hk with an embedded Pkl package so matching-version configs validate offline on a cold cache, adds templated dir support for workspace-aware steps, and lands a new check_after_diff mechanism that lets partial fixers (like ShellCheck) apply what they can while still reporting what they cannot. It also brings several new Go and lint builtins plus a batch of correctness fixes for Go linters, gitleaks, workspace paths, Windows shims, and stashing.

Added

• Embedded matching-version Pkl package (@sahidvelji) #1218. hk now ships the Pkl package built for its own version and seeds HK_PKL_CACHE_DIR with it before evaluating hk.pkl, so a config pinned to that version validates with no network round trip on a cold cache — a fresh clone, CI runner, new container, or upgrade. Cached content always wins over the embedded copy, and other versions are fetched as before. Set HK_PKL_EMBEDDED=0 to disable seeding. Addresses discussion #1216. …

This release expands the dotfiles/bootstrap workflow with previews, bulk capture, git-tracked manifests, and profile reconciliation, adds scoped config collection updates and per-tool postinstall hooks, and rounds it out with a large batch of fixes across tasks, schema validation, Windows, lockfiles, and shims.

Highlights

• Dotfiles management grows a full preview-and-capture workflow: mise bootstrap dotfiles diff, bulk add --changed, git-tracked directory manifests, and automatic reconciliation when a profile switches a target's source.
• mise config set learns idempotent list updates (--append/--remove) and explicit --global/--system targeting, and mise use gains per-tool --postinstall hooks.
• Safer upgrades: replaced tool versions now linger for a grace period instead of being deleted immediately, so a bad upgrade is easier to recover from.

Added

• dotfiles: New mise bootstrap dotfiles diff previews exactly what apply would change without writing anything, printing unified content patches for copy, template, and inline entries and structural summaries for symlinks and directories. Optional target filters use the same selection semantics as apply. (#12511 by @jdx) …

A patch release focused on safety and correctness: unknown profiles now fail loudly instead of silently falling back to defaults, dotenv exports survive Docker Compose interpolation, interactive daemon cache misses regain access to your terminal, and macOS release binaries are now notarized.

Fixed

• Unknown profiles are rejected (#741) -- @jdx. An active profile that has neither a [profiles.<name>] table nor a matching fnox.<name>.toml overlay now errors (listing the available profiles) instead of silently falling back to top-level secrets, which could leak defaults on a typo. Shell integration (hook-env) also refuses unknown profiles. Creating new profiles via set, import, and provider add still works.

• Dotenv export preserves dollar signs (#746) -- @jdx. Secrets containing $ are now emitted in single quotes so Docker Compose no longer interpolates them, falling back to double quotes with \$ escaping when needed. Dotenv import was aligned to match: it reassembles multiline single-quoted values, unescapes \', and treats \$ in double quotes as a literal dollar sign. …

This is a small release focused on bug fixes for npm (aube-backed) installs, HTTP cache cleanup, and Windows config pruning.

Fixed

• npm: Aube-backed npm installs no longer drop a synthetic .npmrc into the per-tool install directory. Install-scoped settings such as minimumReleaseAge, trustPolicyExclude, allowedUnpopularPackages, and (for CLI installs) globalDir/globalBinDir now go into .config/aube/config.toml as typed TOML, while allowBuilds stays in package.json. Inline-table trust_policy_excludes / allow_low_downloads in mise.toml still round-trip correctly. (#12425 by @jdx)
• npm: mise now intercepts the private __node-gyp-bootstrap trampoline that embedded aube's lazy node-gyp shim re-execs. Previously naked-run rewriting turned it into mise run __node-gyp-bootstrap … and failed with "no tasks defined", breaking allow_builds installs whose lifecycle scripts call node-gyp (for example gemini-cli via node-pty). (#12429 by @jdx)
• http: A failed extraction (truncated download, unreadable archive, full disk, or Ctrl-C mid-extraction) no longer leaves a permanent hash-named temp directory behind in http-tarballs. All failure paths now clean up the temp directory. (#12420 by @Marukome0743) …

This release adds a few configuration and task features and delivers a large batch of fixes across completions, tools, lockfiles, tasks, config parsing, and shell integration. It also restores dynamic shell completions that regressed after the recent CLI parser change.

Added

• task: New task_config.excludes lets file-task discovery skip config-root-relative paths, directories, and glob patterns, so accidental TOML files (like a pyproject.toml inside a task directory) or entire subtrees are no longer treated as tasks. The closest config that sets excludes replaces inherited values, and an empty list clears the cascade. Relative task.disable_paths now resolve from the declaring config file. (#12366 by @jdx)

  [task_config]
  excludes = ["scripts/vendor", "**/*.generated.toml"]
  

• config: Project configuration can now be split into visible mise/conf.d/*.toml fragments, mirroring the existing .mise/conf.d and .config/mise/conf.d support but without a hidden dot-directory. Fragments merge alphabetically, mise/config.toml still wins over fragments, and environment-specific and .local variants (for example mise/conf.d/tools.development.toml) follow the usual env config rules. (#12395 by @jdx) …

This release adds package uninstall support to the plugin bootstrap flow and fixes a broad set of task, config, tool, and diagnostic edge cases. Many changes turn silent failures and cryptic errors into actionable messages, so it is largely a robustness and quality-of-life release.

Added

• bootstrap: Package-plugin managers now support pruning via an optional PackageUninstall hook, so mise bootstrap packages prune --manager <plugin> is no longer Homebrew-only. mise records ownership only for packages that go from missing to installed during an install, and prune removes only owned packages that are absent from the current config and trusted tracked configs. Pre-existing and manually installed packages are never claimed, dry-run never invokes the hook, and the keep-set is reloaded after confirmation so newly declared packages cannot be removed without another prompt. (#12332 by @jdx)

Fixed …

This release adds a read-only Keeper Secrets Manager provider and delivers a batch of fixes to file-backed secrets, FIDO2 prompting, and shell integration.

Added

• Keeper Secrets Manager provider (#720) -- @jdx. A new read-only keeper-sm provider backed by Keeper's official Rust SDK. Secret values use Keeper notation such as RECORD_UID/field/password. Authentication works from a JSON config file (KSM_CONFIG / FNOX_KEEPER_CONFIG, or the default ~/.keeper/ksm-config.json), with optional one-time-token bootstrap via KSM_TOKEN / FNOX_KEEPER_TOKEN (which must persist to a file-backed config). Batch reads redeem the token once and fetch concurrently, and Keeper environment variables are scrubbed from the proxy's ambient credentials.

  DB_PASSWORD = { provider = "keeper-sm", value = "RECORD_UID/field/password" }
  

• fnox set --from-file <path> (#730) -- @jdx. Reads a secret value verbatim from a UTF-8 file without trimming, preserving trailing newlines. This fixes SSH private keys and similar as_file secrets losing their required final newline, which happened because fnox set trims stdin values and shell command substitution strips trailing newlines. The existing echo "x" | fnox set KEY behavior is unchanged; --from-file cannot be combined with a positional value.

  fnox set SSH_KEY --from-file ~/.ssh/id_ed25519
  

Fixed …

This release adds opt-in automatic self-updates, lets remote bootstrap leave a working mise behind on each target, and introduces versioned lockfiles that bind each request to the version it resolved. It also replaces the CLI parser with usage-rs, hardens remote Git task handling, and fixes a wide range of tool-installation, task, and config edge cases.

Highlights

• mise can now keep itself up to date and provision itself onto remote hosts, closing two long-standing gaps in unattended and remote workflows.
• Lockfiles gained an explicit format version so overlapping loose and exact requests can pin distinct versions, with mise lock --upgrade for safe migration and no surprise drift for existing files.
• The CLI parser moved from clap to usage-rs, and remote Git task paths are now contained against traversal, symlink, and Windows path escapes.

Added

• self-update: New opt-in automatic updates. Enable auto_update (with auto_update_check_duration, default 7d) and mise will update itself before eligible interactive commands, then re-exec your original invocation with the new binary. Updates are throttled and lock-serialized, skipped in CI, offline, non-interactive, and shell-integration contexts, and failures never block the requested command. Package-managed builds are steered toward the official optimized binaries. (#12288 by @jdx)

  [settings]
  auto_update = true
  auto_update_check_duration = "7d" …
  

This release lets remote bootstrap pick which config environments run on each target, fixes several tool-installation edge cases (archive naming, Windows ZIP preference, renamed aqua packages, Homebrew cask metadata), and hardens pacman package detection and Windows self-update cleanup.

Added

• bootstrap: Remote bootstrap can now select which mise.<env>.toml layers load on each SSH target without inheriting the orchestrator's full environment. Set a default with [bootstrap.remote].mise_env, override per host in your inventory, or pass --remote-env (repeatable or comma-separated) on the command line. (#12182 by @jdx)

  [bootstrap.remote]
  mise_env = ["production"]
  

• bootstrap: Independent config roots can now contribute symlink-each trees that share the same target directory, as long as their leaf paths are disjoint. Overlapping leaves and file/directory collisions still fail before any changes, reporting both declaring config origins. (#12190 by @jdx)

• doctor: mise doctor now detects leftover Windows self-update helper files (__relocated__ / __selfdelete__ copies in TEMP) and reports their count and total size, noting that a subsequent mise self-update removes them. (#12205 by @JamBalaya56562)

Fixed …

This release adds a persistent Pkl package cache with offline evaluation, pinact v4 support, a configurable failed-command output file, and a handful of fixes for binary files, builtin argument handling, worktrees, annotated tags, and step conditions.

Added

• Persistent Pkl package cache and offline mode (@jdx) #1199. Pkl packages are now persisted (by default under the platform cache directory as pklr), so a package downloaded during any prior evaluation stays available even after hk's resolved-config cache is invalidated by a config edit, upgrade, or cache cleanup. This prevents local commits from being blocked when a registry is unreachable. Two new environment variables control the behavior: HK_PKL_CACHE_DIR overrides the cache location, and HK_PKL_OFFLINE=1 disables all network access, failing fast with the missing package URL and cache path instead of hitting the network. Both are read from the environment before hk.pkl is evaluated. Addresses discussion #1198.

• pinact v3 and v4 builtins (@risu729) #1195. The pinact and pinact_update builtins now track the latest major version (currently v4.1.1) and use the v4-native --verify-comment flag. New pinact_v3 and pinact_update_v3 alternatives are available for projects still on pinact v3, without requiring changes to step names.

  // pinact v4 (default) …
  

A small patch release centered on a fix to fnox set so updates no longer clobber a secret's custom remote key name. The rest is routine dependency and CI maintenance.

Fixed

• fnox set preserves an existing remote key name (#712) -- @jdx. When updating a remote-backed secret, fnox set previously resolved the remote key only from --key-name or the environment variable name, overwriting any custom value in your config and writing to the wrong backend object. Now it reuses the existing provider key when one is configured for the same provider, while --key-name still takes highest precedence and the environment key is used as a fallback when creating a secret or switching providers. Inherited parent-config secrets no longer steer a child override.

  As part of this fix, the HashiCorp Vault provider's put_secret was reworked to update individual fields via kv patch (preserving sibling fields), pass values through piped stdin so @ and - are treated literally, and correctly handle missing paths, concurrent writers, and soft-deleted KV v2 metadata.

Full Changelog: https://github.com/jdx/fnox/compare/v1.33.0...v1.33.1

💚 Sponsor fnox …

This release turns hk into a first-class tool for coding agents, adding an MCP server, an interactive dashboard, structured and machine-readable output, command effect safety, normalized diagnostics with SARIF export, and one-command integration snippets for popular agents and editors. It also adds a Kingfisher secret-scanner builtin and fixes a couple of file-selection and command-composition bugs.

Highlights

• A complete agent-native workflow: drive hk from anywhere with --cd/--files0-from, get machine-readable results via --format json|jsonl, gate risky steps with --safe, export findings as SARIF, and expose everything to agents over MCP with a live dashboard.
• New hk agent command tree prints ready-to-paste instruction, hook, and MCP setup snippets for Codex, Claude Code, Claude Desktop, and VS Code.

Added

• MCP server for coding agents (@jdx) #1169. hk mcp [--root <path>] starts a STDIO-only Model Context Protocol server built on the official Rust MCP SDK. Agents can inspect projects, read effect-aware execution plans, run all-or-nothing safe checks and fixes, poll run lifecycle, cancel runs, and page through logs and captured diffs. Tools are constrained to canonical startup roots plus client-provided roots, with one active run per root and bounded output/run retention. There is no HTTP listener, hosted service, auth system, or unrestricted shell tool.

  hk mcp --root /path/to/project
  ``` …
  

A small release that adds custom field support to the Bitwarden provider, plus a documentation cleanup for personal age-based sync. The rest of the release is routine dependency and CI maintenance.

Added

• Bitwarden custom field support (#690) -- @jdx. In addition to the standard username, password, notes, uri, and totp fields, any other field name in a item/field reference is now resolved as a custom field. With the default bw backend, fnox fetches the full item JSON and extracts the matching field (case-sensitive); with the rbw backend it uses the --field flag.

  API_KEY = { provider = "bitwarden", value = "Database/API Key" }
  

Fixed

• Bitwarden custom field names containing slashes (#693) -- @jdx. References now split only on the first /, so custom field names such as Database/API/Key resolve correctly. This also removes the previous "too many slashes" error for references with more than one /.

Documentation

• Clarified personal age provider setup for sync (#692) -- @jdx. The sync guide now uses a dedicated sync-age provider with the --local-file flag, corrects the invalid fnox set --provider age setup step, explains how provider definitions replace by name rather than deep-merging, and distinguishes a personal sync cache from team-encrypted secrets in git. …

A small patch release focused on bug fixes across stashing, builtins, config error handling, and conventional-commit validation.

Fixed

• Fixer output preserved with stage=false / fail_on_fix=true (@jdx) #1145. When smart stashing was combined with disabled auto-staging, stash restoration used the post-hook index as the fixer side of its three-way merge. Since the fixer only touched the isolated worktree in that mode, restoration saw no change and silently discarded the formatter output. hk now uses worktree content as the fixer input, merges it with the user's saved unstaged edits, and leaves the original index untouched. Fixes discussion #1144.

• Ruff builtins detect extensionless Python scripts (@jdx) #1147. The ruff and ruff_format builtins previously matched files only with **/*.py and **/*.pyi globs. They now select files using hk's Python type detection, so extensionless scripts with a Python shebang are linted and formatted alongside .py and .pyi files. Fixes discussion #1146. …

A feature-packed release adding a destination-scoped credential proxy, a process-replacement mode for exec, a new Azure App Configuration provider, and IAM role assumption for the AWS providers, plus a fix to how global config layers under explicit --config paths.

Highlights

• New ways to keep real secrets out of workloads: a credential proxy that brokers HTTPS requests without exposing secret values, and an exec --replace mode for clean environment-only execution.
• Broader cloud coverage: a read-only Azure App Configuration provider and cross-account IAM role assumption in the AWS providers.

Added

Credential proxy (#667) -- @jdx

A new [proxy] configuration and fnox proxy command let agent-style workloads call external APIs without ever receiving real secret values in their environment. fnox runs an ephemeral loopback TLS interception proxy that substitutes credentials into allowed request headers only for destinations that match your rules, and redacts reflected secret values from responses.

fnox proxy rules            # inspect the effective policy
fnox proxy run -- ./agent   # run a command through the local proxy
``` …

17% smaller, up to 31% faster

Compared with v1.53.0, the published x86_64-unknown-linux-gnu release is substantially leaner and faster:

Measurement	v1.53.0	v1.54.0	Improvement
Compressed archive	8.19 MB	7.06 MB	13.8% smaller
Extracted binary	22.01 MB	18.27 MB	17.0% smaller
Startup (--version)	2.21 ms	1.52 ms	31.2% faster
Builtins loading	2.31 ms	1.62 ms	29.8% faster
Config validation	3.69 ms	2.94 ms	20.3% faster
Representative check --all	14.62 ms	13.47 ms	7.8% faster

Measurements use the published release binaries with hermetic state, warm caches, shell overhead excluded, and execution pinned to one CPU. Real hook runs dominated by external linters will see a smaller overall percentage.

---

This release adds an opt-in way to focus detailed check diagnostics on only the files that actually failed, teaches hk's usage spec to declare each command's effect on the world, and speeds up the mixed-line-ending and check-merge-conflict builtins along with a new PGO/BOLT-optimized Linux release binary. It also fixes noise and false errors in a couple of builtins.

Added …