Skip to content

FAQ

Installation

Q: pip install ipman-cli fails with "no matching distribution found"

Two common causes:

Cause 1 (most common): Python version below 3.10

IpMan requires Python >= 3.10. When your Python version doesn't meet the requirement, PyPI finds no compatible distribution.

Cause 2: VPN / proxy causing SSL connection failure

Under VPN or corporate networks, pip may fail to connect to PyPI due to SSL certificate verification failure. The error can sometimes appear as "no matching distribution" (accompanied by SSL warnings). See SSL errors below.

Troubleshooting steps:

# 1. Check Python version (must be >= 3.10)
python3 --version

# 2. If version is sufficient, test PyPI connectivity
pip index versions ipman-cli

Solutions: - Version issue: upgrade Python to 3.10+ - Network issue: see SSL errors below

macOS users can install via Homebrew:

brew install python@3.12

Then set it as default — see Installation Guide.

Q: How to set Homebrew Python 3.12 as default on macOS?

Add PATH configuration to ~/.zshrc:

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. This method safely shadows the system version via PATH priority.

Q: pip install fails with "externally-managed-environment" on Python 3.12

Cause: Python 3.12 enforces PEP 668, preventing pip from installing packages into Homebrew-managed Python environments.

Recommended: Use pipx for CLI tools:

brew install pipx
pipx ensurepath
pipx install ipman-cli

pipx automatically creates an isolated virtual environment for ipman-cli.

VPN users: If pipx also fails with SSL errors, add trusted hosts: 

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

Alternative: Create a virtual environment manually:

python3 -m venv ~/.ipman-venv
source ~/.ipman-venv/bin/activate
pip install ipman-cli

Not recommended: pip install --break-system-packages ipman-cli bypasses the restriction but may corrupt Homebrew's Python packages.

Q: pip install fails with "SSL: CERTIFICATE_VERIFY_FAILED"

Typical error:

WARNING: Retrying ... after connection broken by 'SSLError(SSLCertVerificationError(1,
'[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate'))'

Cause: Usually VPN, corporate proxy, or missing CA root certificates preventing pip from verifying PyPI's SSL certificate.

Solution 1: VPN / corporate proxy (most common)

Temporarily skip SSL verification:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org ipman-cli

For pipx users:

pipx install ipman-cli --pip-args="--trusted-host pypi.org --trusted-host files.pythonhosted.org"

Tip: To make this permanent, add to ~/.pip/pip.conf: 

[global]
trusted-host =
    pypi.org
    files.pythonhosted.org

Solution 2: Missing CA certificates on macOS

brew install ca-certificates

Solution 3: Add corporate root certificate to trust chain

If your company network uses an SSL MITM proxy, import the corporate root certificate:

# Get the root certificate from your IT department, then:
# macOS: double-click the .crt file to import into Keychain, set to "Always Trust"
# Or: specify via environment variable
export SSL_CERT_FILE=/path/to/company-root-ca.crt

Q: Which Python versions are supported?

IpMan requires Python >= 3.10. Python 3.12 or later is recommended.

Python 3.9 and below are not supported because the project uses 3.10+ language features (e.g. match/case pattern matching, X | Y type union syntax).

Q: Which operating systems are supported?

The core workflow is verified on macOS with Claude Code. Linux is expected to work (same symlink semantics) but is not part of the verified matrix yet. On Windows, per-skill operations run in a native mode and are covered by CI; directory-level takeover/release is not yet Windows-verified (it's gated behind a Windows canary that hasn't shipped).

Usage

Q: Which AI agent tools does IpMan support?

  • Claude Code (.claude/skills/) — verified target
  • OpenClaw (.openclaw/skills/) — path mapping only, unverified

The store and lockfile are agent-agnostic; adding an agent is a one-line path mapping. The next verified agent will be chosen based on real user demand.

Q: Does IpMan install skills?

No — by design. Your agent's native mechanisms install; IpMan organizes what is already on the machine (absorb/dedup/clean/enable/disable/packs/custody). The legacy add/install commands still execute but are hidden and dormant.

Q: Is disable the same as deleting?

No. disable removes only the symlink; the original stays in the store and the version pin stays in the ledger — enable restores it exactly. Deleting happens only via clean --empty-trash, and only for things you first quarantined.

Q: Should I commit ip.lock?

Yes — both ip.yaml and ip.lock if the project uses ipman-managed skills. Anyone who clones the repo runs uvx ipman-cli sync and gets the exact same skill sources. The managed symlinks themselves are git-ignored automatically.

Q: sync on my other machine complains about portable: false

Skills added from a local path (including --adopt) can't be reproduced on a machine that doesn't have that path. Use a git URL source for anything that must travel; local sources are best for skills you develop yourself.

Q: Where did ipman install / ipman hub go?

They're dormant, not gone — still executable, hidden from --help. The core surface is now init/add/sync/list/remove/update/doctor. See Dormant Features.

Q: ipman init used to set up my shell — what changed?

Shell integration moved to ipman shell init. Legacy invocations with explicit shell arguments (e.g. ipman init zsh) still work and forward with a deprecation notice; bare ipman init now initializes the project (ip.yaml).

Q: I tried to absorb a toolkit clone (e.g. gstack) and it refused — why?

Because other skills depend on it. A toolkit like gstack is a git clone, and dozens of your other skills are thin wrappers whose SKILL.md is a symlink pointing into that clone. Absorbing (moving) the clone would break every one of them — silently. IpMan detects the dependents and refuses, naming them. The right protection for a toolkit is directory custody (ipman takeover): the whole skills directory goes into IpMan's keeping with the toolkit and its wrappers preserved in place, so its own updater keeps working. A plain git clone that nothing else depends on absorbs fine (with an upstream-loss note).

Q: Why can't suite-managed skills (e.g. gstack's) be absorbed?

By design. A "suite" skill is a directory whose files are already symlinks into a toolkit's own clone — the content lives there, managed by the suite's own updater. Absorbing would capture a shell of pointers (no dedup or space benefit) and then fight the updater on every upgrade. To protect suite skills, use directory custody (ipman takeover): the whole skills dir moves into IpMan's keeping with suite wrappers preserved as-is (relative links rewritten to absolute), so the suite updater keeps working and you gain rm-rf survivability.

Q: How to check the installed version?

ipman --version

Q: How do I update IpMan?

The CLI is the single authority for the companion skill, so the two move in lock-step. Easiest path: run the /ipman-update skill from your agent — it detects how IpMan was installed (pipx / uv / pip), checks PyPI, asks before upgrading the CLI, then regenerates the companion skill to match.

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

Q: Can I use IpMan in Chinese?

Yes — automatically. If your LC_ALL, LANG or LANGUAGE starts with zh, all output (status values, errors, the TUI, CLI text) is Chinese; otherwise English. There is no flag or setting to toggle — it follows your locale.

Q: How do I put IpMan in my status bar?

ipman statusline prints one compact line (e.g. 📦 user⚑12 | proj✓3 | !1断链) in well under 50 ms, with no deep scan. Wire it into Claude Code's settings.json:

{
  "statusLine": { "type": "command", "command": "ipman statusline" }
}

Q: What does suite:gstack mean?

Some skills aren't self-contained folders — they're thin wrappers whose files symlink into a toolkit's own git clone (a "suite"). IpMan labels those with the suite root they belong to, e.g. suite:gstack means the skill is a wrapper into the gstack toolkit clone. scan also tallies them ("Suites detected: gstack: 55 skills") and the TUI shows 套件·gstack. Suite skills are never absorbed — the content lives in the clone and its own updater manages it; to protect them, use directory custody (ipman takeover).