# pipx Migration Guide

## Overview

The `openclaw-installer` package has been migrated from `pip` to `pipx` as the recommended installation method. This provides better isolation and avoids dependency conflicts.

## Why pipx?

| Feature | pip | pipx |
|---------|-----|------|
| **Isolation** | ❌ Installs in system/user Python | ✅ Isolated virtual environment |
| **Dependencies** | ❌ Can conflict with other packages | ✅ No dependency conflicts |
| **CLI Tools** | ⚠️ Manual PATH management | ✅ Automatic PATH setup |
| **Upgrades** | ⚠️ May break other packages | ✅ Safe isolated upgrades |

## Installation Instructions

### 1. Install pipx

**Official documentation:** https://pipx.pypa.io/stable/installation/

#### macOS
```bash
brew install pipx
pipx ensurepath
```

#### Linux (Debian/Ubuntu)
```bash
sudo apt install pipx
pipx ensurepath
```

#### Linux (Fedora)
```bash
sudo dnf install pipx
pipx ensurepath
```

#### Windows
```powershell
# Requires Python 3.8+
python -m pip install --user pipx
python -m pipx ensurepath
```

Or using WinGet:
```powershell
winget install pipx
```

#### From Source (Any Platform)
```bash
python -m pip install --user pipx
python -m pipx ensurepath
```

### 2. Install openclaw-installer

```bash
pipx install openclaw-installer
```

### 3. Verify Installation

```bash
openclaw-installer --version
openclaw-installer --help
```

## Managing openclaw-installer

### Upgrade
```bash
pipx upgrade openclaw-installer
```

### Reinstall
```bash
pipx reinstall openclaw-installer
```

### Uninstall
```bash
pipx uninstall openclaw-installer
```

### List All pipx Packages
```bash
pipx list
```

## Files Updated

| File | Change |
|------|--------|
| `README.md` | Updated installation instructions to use pipx |
| `PUBLISH.md` | Updated testing and verification commands |
| `automation/README.md` | Added pipx prerequisite |
| `pyproject.toml` | Removed conflicting `nodejs-bin` dependency |

## Dependency Fix

The `nodejs-bin>=22.0` dependency has been removed because it doesn't exist for macOS/Linux. Node.js is now downloaded automatically by the installer for all platforms.

## For Developers

For local development, you can still use pip with a virtual environment:

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\activate   # Windows

# Install in editable mode
pip install -e .
```

## Troubleshooting

### pipx command not found
```bash
# After installing pipx, run:
pipx ensurepath
# Then restart your terminal
```

### PATH warning after installing openclaw-installer
If you see:
```
⚠️  Note: '/Users/username/.local/bin' is not on your PATH environment variable.
```

Fix it:
```bash
pipx ensurepath
```

Then restart your terminal or reload shell config:
```bash
source ~/.zshrc   # macOS Catalina+ (zsh)
# or
source ~/.bashrc  # Linux or older macOS
```

### openclaw-installer not in PATH
```bash
# Check if pipx bin directory is in PATH
pipx ensurepath
# Restart terminal
```

### Upgrade issues
```bash
# Force reinstall
pipx reinstall openclaw-installer

# Or uninstall and reinstall
pipx uninstall openclaw-installer
pipx install openclaw-installer
```

## Version History

| Version | Install Method | Notes |
|---------|---------------|-------|
| 1.0.0 | `pip install` | Initial release |
| 1.0.1 | `pipx install` | Migrated to pipx, removed nodejs-bin dependency |

## Links

- **pipx Documentation:** https://pipx.pypa.io/stable/
- **pipx Installation:** https://pipx.pypa.io/stable/installation/
- **PyPI Package:** https://pypi.org/project/openclaw-installer/
