248 lines
4.4 KiB
Markdown
248 lines
4.4 KiB
Markdown
# 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
|