Skip to content

Installation

Requirements

  • Python: >= 3.10 (3.12+ recommended)
  • git: >= 2.30 recommended (the store uses git worktrees)
  • OS: macOS (verified) / Linux (expected to work) / Windows (per-skill ops run in native mode and are CI-covered; directory takeover/release not yet Windows-verified)
  • An AI agent that reads project skills — Claude Code is the verified target

Quick Install

# macOS
brew install pipx
pipx ensurepath
pipx install ipman-cli

# Linux / Windows
pip install pipx
pipx install ipman-cli

VPN / Corporate network users: If you encounter SSL certificate errors, use: 

pipx install ipman-cli --pip-args="--trusted-host pypi.org --trusted-host files.pythonhosted.org"
See FAQ - SSL errors for details.

Via pip

pip install ipman-cli

Note: Python 3.12+ Homebrew environments block global installs due to PEP 668. Use pipx or a virtual environment instead.

Via uv

uv pip install ipman-cli

Via curl (Linux / macOS)

curl -sSL https://raw.githubusercontent.com/twisker/ipman/main/install.sh | bash

Pre-built Binaries (paused)

Older releases shipped PyInstaller binaries on GitHub Releases. Binary builds are paused — existing downloads lag behind the current version. Install via pip/pipx/uv instead.

One-off runs without installing

uvx ipman-cli sync    # restore a repo's skill environment with zero setup

macOS Detailed Steps

If your macOS ships with Python < 3.10 (e.g. 3.9), install a newer version first.

1. Install Python 3.12

brew install python@3.12

2. Set Python 3.12 as Default

echo 'export PATH="$(brew --prefix python@3.12)/libexec/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify:

python3 --version   # Should show 3.12.x
which python3       # Should point to Homebrew path

Note: Do not delete or overwrite /usr/bin/python3 — macOS system tools depend on it. The PATH trick safely shadows the system version.

3. Install pipx and IpMan

brew install pipx
pipx ensurepath
pipx install ipman-cli

Verify Installation

ipman --version
ipman info

Keeping It Updated

The CLI is the sole authority for the companion skill, so upgrade them together. Run the /ipman-update skill from your agent (it detects pipx/uv/pip, checks PyPI, and asks before upgrading), or do it by hand:

pipx upgrade ipman-cli   # or: uv tool upgrade ipman-cli / pip install -U ipman-cli
ipman skill-sync         # regenerate the companion skill against the new CLI

Shell Completion

IpMan uses Click, which supports shell completion:

# Bash
eval "$(_IPMAN_COMPLETE=bash_source ipman)"

# Zsh
eval "$(_IPMAN_COMPLETE=zsh_source ipman)"

# Fish
_IPMAN_COMPLETE=fish_source ipman | source

Install from Source (Developers)

git clone https://github.com/twisker/ipman.git
cd ipman
uv venv
uv pip install -e ".[dev]"