Configuration files¶

Keep the roles separate — ixt.toml is human intent, ixt.lock is the generated exact resolution, registry.toml maps short names.

Files and audiences¶

ixt has one user manifest, one generated lockfile, and one registry config. Keep them straight:

The rest of this page focuses on ixt.toml and ixt.lock. The registry is covered on its own page.

Mental model — intent, lock, snapshot¶

ixt distinguishes three state surfaces, and you should keep them straight.

ixt.lock¶

ixt.lock is generated TOML. It lives beside the ixt.toml that produced it: project manifests get a project ixt.lock, and the global manifest gets $IXT_HOME/config/ixt.lock.

ixt lock write
ixt lock check
ixt lock diff
ixt tool apply --locked --strict

ixt lock write resolves the effective ixt.toml without installing tools. The lock records a manifest fingerprint, exact versions, exposure and injection policy, and binary release asset metadata when a GitHub/GitLab binary tool is declared.

Use ixt lock check or ixt lock diff before CI materialization. Use ixt tool apply --locked --strict when the machine must match the committed lock exactly. Do not hand-edit ixt.lock; change ixt.toml, then regenerate the lock. Checks and strict preflight are local and stable when an upstream publishes a newer version; ixt lock write is the explicit network-resolving operation used to refresh the recorded versions and assets.

ixt.toml¶

ixt.toml is the declarative configuration file for managing tools. It can live in your project root or in $IXT_HOME/config/.

[tools]
"@pypi:ruff" = {}
"@pypi:mypy" = {}
"@npm:@biomejs/biome" = {}
"@gh:BurntSushi/ripgrep" = {}

[tools]
# Version pinning
"@pypi:ruff" = { version = "==0.5.0" }
"@gh:sharkdp/fd" = { version = "==10.2.0" }

# Exposure control
"@pypi:httpie" = { expose = ["http", "https"] }
"@gh:BurntSushi/ripgrep" = { expose = ["rg:ripgrep"] }

# Explicit backend
"@npm:prettier" = {}
"@gl:gitlab-org/cli" = {} # binary backend, GitLab host

Fields¶

Exposure rules¶

Exposure controls which binaries a tool makes available in $IXT_HOME/installed/bin/.

Built-in rules¶

Explicit binaries¶

[tools]
httpie = { expose = ["http", "https"] }

Aliases¶

Rename a binary at link time with the syntax <binary-in-env>:<shim-on-PATH>:

• Left side — the real file name inside the tool's isolated env (must match an actual binary that the package ships, e.g. rg for ripgrep).
• Right side — the name of the shim created in $IXT_HOME/installed/bin/ (what the user will type on the command line).

Both sides must be portable basenames, not paths. ixt rejects separators, absolute paths, ./.., control characters, and reserved Windows device names before creating, replacing, or removing any shim.

For example, BurntSushi/ripgrep ships a binary called rg. The rule "rg:ripgrep" picks up that rg binary and exposes it as ripgrep on your PATH:

[tools]
"@gh:BurntSushi/ripgrep" = { expose = ["rg:ripgrep"] }

Workflow: export → lock → commit → apply¶

ixt tool export > ixt.toml

ixt lock write
ixt lock check

git add ixt.toml ixt.lock
git commit -m "pin dev toolchain"

# On another machine or in CI
ixt tool apply --locked --strict              # installs exactly what's locked
ixt tool apply --locked --strict --remove --yes # also removes anything not listed (CI)

ixt tool apply reference