# Installation Guide

Complete installation instructions for CmdForge.

## Quick Install

```bash
git clone https://gitea.brrd.tech/rob/CmdForge.git
cd CmdForge
pip install -e .
export PATH="$HOME/.local/bin:$PATH"
cmdforge providers install
```

## Detailed Installation

### Step 1: Install Python 3.10+

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install python3 python3-pip
```

**macOS:**
```bash
brew install python@3.11
```

**Verify:**
```bash
python3 --version  # Should be 3.10 or higher
```

### Step 2: Install CmdForge

```bash
git clone https://gitea.brrd.tech/rob/CmdForge.git
cd CmdForge
pip install -e .
```

**With TUI and development dependencies:**
```bash
pip install -e ".[dev]"
```

### Step 3: Configure PATH

CmdForge creates executable wrappers in `~/.local/bin/`. Add this to your shell config:

**Bash (~/.bashrc):**
```bash
export PATH="$HOME/.local/bin:$PATH"
```

**Zsh (~/.zshrc):**
```bash
export PATH="$HOME/.local/bin:$PATH"
```

**Fish (~/.config/fish/config.fish):**
```fish
set -gx PATH $HOME/.local/bin $PATH
```

Then reload:
```bash
source ~/.bashrc  # or restart terminal
```

### Step 4: Install an AI Provider

You need at least one AI CLI tool. The easiest way is the interactive installer:

```bash
cmdforge providers install
```

This guides you through installing and authenticating providers.

#### Manual Installation

**OpenCode (free tier available):**
```bash
curl -fsSL https://opencode.ai/install | bash
source ~/.bashrc  # or start new shell
opencode  # Opens browser for sign-in
```

**Claude CLI (pay-per-use):**
```bash
npm install -g @anthropic-ai/claude-code
claude  # Opens browser for sign-in
```

**Codex (pay-per-use):**
```bash
npm install -g @openai/codex
codex  # Opens browser for sign-in
```

**Gemini (free tier available):**
```bash
npm install -g @google/gemini-cli
gemini  # Opens browser for Google sign-in
```

**Ollama (free, runs locally):**
```bash
curl -fsSL https://ollama.ai/install.sh | bash
ollama pull llama3
cmdforge providers add ollama "ollama run llama3" -d "Local Llama 3"
```

See [PROVIDERS.md](PROVIDERS.md) for full provider setup instructions.

### Step 5: Verify Installation

```bash
# Check CmdForge is installed
cmdforge --version

# List configured providers
cmdforge providers list

# Check which providers are available
cmdforge providers check

# Test with mock provider (no AI needed)
echo "hello world" | cmdforge run --provider mock
```

### Step 6: Create Wrapper Scripts

After installation or any Python environment change:

```bash
cmdforge refresh
```

This creates executable scripts in `~/.local/bin/` for all your tools.

## Installing Example Tools

### Quick Install (All 28 Tools)

```bash
python examples/install.py
cmdforge refresh
```

### Manual Install

Copy individual tool configs to `~/.cmdforge/<toolname>/config.yaml`.

See [EXAMPLES.md](EXAMPLES.md) for all tool configurations.

## Troubleshooting

### "cmdforge: command not found"

PATH is not configured. Add to your shell config:
```bash
export PATH="$HOME/.local/bin:$PATH"
```

### "Provider 'X' not found"

1. Check provider is installed: `which claude` or `which opencode`
2. Check provider is configured: `cmdforge providers`
3. Add missing provider: `cmdforge providers add`

### "Permission denied" on tool execution

Refresh wrapper scripts:
```bash
cmdforge refresh
```

### TUI doesn't start / looks broken

Install urwid:
```bash
pip install urwid
```

Ensure your terminal supports mouse (most modern terminals do).

### Tools work with `cmdforge run` but not directly

The wrapper scripts may be outdated. Refresh them:
```bash
cmdforge refresh
```

### Python version mismatch

If you have multiple Python versions, ensure CmdForge uses the right one:
```bash
python3.11 -m pip install cmdforge
```

## Uninstalling

```bash
# Remove package
pip uninstall cmdforge

# Remove config and tools (optional)
rm -rf ~/.cmdforge

# Remove wrapper scripts (optional)
rm ~/.local/bin/{summarize,translate,fix-grammar,...}
```

## Upgrading

```bash
pip install --upgrade cmdforge
cmdforge refresh
```

## Directory Structure

After installation:

```
~/.cmdforge/
├── providers.yaml          # Provider configurations
├── summarize/
│   └── config.yaml         # Tool config
├── translate/
│   ├── config.yaml
│   └── prompt.txt          # External prompt file (optional)
└── ...

~/.local/bin/
├── cmdforge              # Main command
├── summarize               # Tool wrapper script
├── translate               # Tool wrapper script
└── ...
```

## Next Steps

1. [Set up providers](PROVIDERS.md)
2. [Browse example tools](EXAMPLES.md)
3. Run `cmdforge ui` to create your first tool