# Installation Guide

Complete installation instructions for SmartTools.

## Quick Install

```bash
pip install smarttools
export PATH="$HOME/.local/bin:$PATH"
smarttools refresh
```

## 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 SmartTools

**From PyPI (recommended):**
```bash
pip install smarttools
```

**From source (for development):**
```bash
git clone https://gitea.brrd.tech/rob/smarttools.git
cd smarttools
pip install -e .
```

**With TUI support (recommended):**
```bash
pip install smarttools urwid
```

### Step 3: Configure PATH

SmartTools 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. Choose based on your needs:

#### Free Options

**OpenCode (recommended for free):**
```bash
# Install
curl -fsSL https://opencode.ai/install | bash

# Authenticate (uses browser)
~/.opencode/bin/opencode auth
```

#### Paid Options

**Claude CLI:**
```bash
# Install
npm install -g @anthropic-ai/claude-cli

# Authenticate
claude auth
```

**Gemini CLI:**
```bash
# Install
pip install google-generativeai

# Or the CLI wrapper
npm install -g @anthropic-ai/gemini-cli
```

**Codex (OpenAI):**
```bash
npm install -g codex-cli
codex auth
```

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

### Step 5: Verify Installation

```bash
# Check SmartTools is installed
smarttools --version

# List available providers
smarttools providers

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

### Step 6: Create Wrapper Scripts

After installation or any Python environment change:

```bash
smarttools refresh
```

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

## Installing Example Tools

### Quick Install (All 28 Tools)

```bash
curl -sSL https://raw.githubusercontent.com/yourusername/smarttools/main/examples/install.py | python3
smarttools refresh
```

### Manual Install

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

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

## Troubleshooting

### "smarttools: 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: `smarttools providers`
3. Add missing provider: `smarttools providers add`

### "Permission denied" on tool execution

Refresh wrapper scripts:
```bash
smarttools 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 `smarttools run` but not directly

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

### Python version mismatch

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

## Uninstalling

```bash
# Remove package
pip uninstall smarttools

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

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

## Upgrading

```bash
pip install --upgrade smarttools
smarttools refresh
```

## Directory Structure

After installation:

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

~/.local/bin/
├── smarttools              # 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 `smarttools ui` to create your first tool