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 git+https://gitlab.com/pytgaen-group/ixt.git@v0.7.0 |
pipx install git+https://gitlab.com/pytgaen-group/ixt.git@v0.7.0 |
ixt setup path |
| macOS | brew install uv, then uv tool install git+https://gitlab.com/pytgaen-group/ixt.git@v0.7.0 |
pipx install git+https://gitlab.com/pytgaen-group/ixt.git@v0.7.0 |
ixt setup path |
| Windows PowerShell | winget install --id=astral-sh.uv -e, then uv tool install git+https://gitlab.com/pytgaen-group/ixt.git@v0.7.0 |
pipx install git+https://gitlab.com/pytgaen-group/ixt.git@v0.7.0 |
ixt setup path --shell pwsh |
pipx install git+https://gitlab.com/pytgaen-group/ixt.git@v0.7.0 also works when pipx is already your Python tool manager, but uv is the recommended path.
Why uv tool install?
ixt itself follows its own philosophy: install it in isolation. Any uv tool method works; uvx --from git+... ixt --help is still useful for one-shot testing.
Verify integrity (optional)¶
Release tags are SSH-signed. The one-liner uv tool install git+... above is pinned but does not verify the 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 v0.7.0 # SSH signature
# 2. Install from the verified tag checkout
git checkout --detach v0.7.0
uv tool install .
When to bother
CI and prod machines: always. Dev machines: your call — but if you skipped the verify, the git+ 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:
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.
Your first tools¶
One command per ecosystem — each gets its own isolated env.
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.
Uses bun (bootstrapped automatically) for fast, isolated Node tool installation.
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:
Version pinning¶
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
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)
Health check¶
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.