Skip to content

🚀 Getting started

From zero to your first isolated tool in under a minute.

Installation

Platform Recommended path Fallback path PATH setup
Linux uv tool install ixt-cli pipx install ixt-cli ixt setup path
macOS brew install uv, then uv tool install ixt-cli pipx install ixt-cli ixt setup path
Windows PowerShell winget install --id=astral-sh.uv -e, then uv tool install ixt-cli pipx install ixt-cli ixt setup path --shell pwsh

Only Ubuntu 24.04 on x86_64 is continuously tested. Alpine and Fedora have manual E2E runners. macOS, Windows and ARM are not currently tested and carry no support guarantee; runtime policy isolation is Linux-only.

uv tool install ixt-cli
ixt setup path

The PyPI package is named ixt-cli; it installs the ixt command. pipx install ixt-cli also works when pipx is already your Python tool manager, but uv is the recommended path.

brew install uv
uv tool install ixt-cli
ixt setup path

winget install --id=astral-sh.uv -e
uv tool install ixt-cli
ixt setup path --shell pwsh

If you prefer pipx, install ixt with:

pipx install ixt-cli
ixt setup path --shell pwsh

git clone https://gitlab.com/pytgaen-group/ixt.git
cd ixt
uv tool install -e .

Why uv tool install?

ixt itself follows its own philosophy: install it in isolation. Any uv tool method works; uvx --from ixt-cli ixt --help is still useful for one-shot testing.

Verify integrity (optional)

Release tags are SSH-signed. The one-liner uv tool install ixt-cli above installs from PyPI but does not verify the Git tag signature locally — if you care about the trust chain, use this verify-then-install flow instead:

# 1. Clone the repo and verify the signed tag
git clone https://gitlab.com/pytgaen-group/ixt.git && cd ixt
git fetch --tags
git verify-tag vX.Y.Z                       # SSH signature

# 2. Install from the verified tag checkout
git checkout --detach vX.Y.Z
uv tool install .

When to bother

CI and prod machines: always. Dev machines: your call — but if you skipped the verify, the uv tool install ixt-cli one-liner is all you got.

Add to PATH

After installing, put the ixt shim directory on your PATH so tools installed by ixt are reachable:

ixt setup path

Restart your shell (or source your rc file) so the change takes effect. ixt detects bash / zsh / fish / pwsh and edits the right config file. On Windows, ixt setup path --shell pwsh writes the PowerShell profile path; when no POSIX shell is detected, ixt can add the shim directory to the user PATH in the registry.

Check without modifying

ixt setup path --check tells you the current state without touching anything.

Config and cache paths

ixt environment prints the exact paths for your machine.

Area Unix default Windows PowerShell recommendation
Home/config/install state $XDG_DATA_HOME/ixt or ~/.local/share/ixt Set $env:IXT_HOME = "$env:APPDATA\ixt" if you want an AppData-rooted install
User config $IXT_HOME/config/ixt.toml $env:IXT_HOME\config\ixt.toml when IXT_HOME is set
Cache $IXT_CACHE_HOME, $XDG_CACHE_HOME/ixt, or ~/.cache/ixt Set $env:IXT_CACHE_HOME = "$env:LOCALAPPDATA\ixt\cache" if you want a native Windows cache path
Exposed shims $IXT_HOME/installed/bin or $IXT_BIN_DIR $env:IXT_HOME\installed\bin or $env:IXT_BIN_DIR

Use IXT_HOME when you want to move config plus installed state together. Use IXT_CACHE_HOME for regenerable downloads and metadata only.

Network and privacy

ixt has no telemetry and no background network activity. Network access happens only when an explicit command needs remote metadata or downloads: installs, upgrades, doctor with network checks enabled, and future audit/resolve flows. Use ixt doctor --no-network for an offline diagnostic pass.

For CI/CD examples and cache recommendations, use the separate CI usage guide.

Shell completions

Completion scripts are generated from the real argparse command tree, so the documented commands, fixed choices, and file/directory hints stay aligned with the CLI.

eval "$(ixt setup completions --shell zsh)"

eval "$(ixt setup completions --shell bash)"

ixt setup completions --shell fish | source

Your first tools

One command per ecosystem — each gets its own isolated env.

ixt tool install ruff
ruff --version

ixt creates an isolated venv per tool using uv venv + uv pip install — not uv tool install. uv is already on your system since you used it to install ixt.

ixt tool install @biomejs/biome
biome --version

Uses bun (bootstrapped automatically) for fast, isolated npm package installation.

ixt tool install BurntSushi/ripgrep
rg --version

Downloads the right binary for your platform. No runtime needed — pure Python stdlib.

Auto-detection

ixt picks the backend from the package name. No flag needed in most cases.

Format Backend Example
name PyPI ruff, mypy, httpie
@scope/name npm @google/gemini-cli
owner/repo GitHub Releases BurntSushi/ripgrep

Force a backend

When auto-detection isn't what you want, use namespace prefixes:

ixt tool install @pypi:ruff
ixt tool install @npm:prettier
ixt tool install @gh:BurntSushi/ripgrep

Version pinning

ixt tool install sharkdp/fd@10.2.0    # exact version
ixt tool install sharkdp/fd@10        # latest 10.x.x

ixt tool install ruff>=0.5.0
ixt tool install ruff==0.5.0

Managing tools

ixt tool list                # what's installed
ixt tool info ruff           # details for one tool
ixt tool upgrade ruff        # upgrade one
ixt tool upgrade --all       # upgrade everything
ixt tool uninstall ruff      # clean removal

Full command reference

Declarative setup — ixt.toml

Capture your tools in a config file, commit it, replay anywhere.

ixt tool export > ixt.toml   # snapshot current state (preserves install intent)
ixt tool apply               # install from config (on another machine / CI)

Configuration guide

Health check

ixt doctor

Reports shell/PATH state, install-mode detection with the matching ixt tool upgrade command, managed and system runtimes (uv, bun), registry connectivity, installed tool count, and cache sizes. It prints concrete repair commands where possible, including ixt runtime upgrade <name> for broken or stale ixt-managed runtimes.