smarttools/docs/INSTALL.md

Installation Guide

Complete installation instructions for SmartTools.

Quick Install

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

Detailed Installation

Step 1: Install Python 3.10+

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip

macOS:

brew install python@3.11

Verify:

python3 --version  # Should be 3.10 or higher

Step 2: Install SmartTools

From PyPI (recommended):

pip install smarttools

From source (for development):

git clone https://github.com/yourusername/smarttools.git
cd smarttools
pip install -e .

With TUI support (recommended):

pip install smarttools urwid

Step 3: Configure PATH

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

Bash (~/.bashrc):

export PATH="$HOME/.local/bin:$PATH"

Zsh (~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

Fish (~/.config/fish/config.fish):

set -gx PATH $HOME/.local/bin $PATH

Then reload:

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):

# Install
curl -fsSL https://opencode.ai/install | bash

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

Paid Options

Claude CLI:

# Install
npm install -g @anthropic-ai/claude-cli

# Authenticate
claude auth

Gemini CLI:

# Install
pip install google-generativeai

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

Codex (OpenAI):

npm install -g codex-cli
codex auth

See PROVIDERS.md for full provider setup instructions.

Step 5: Verify Installation

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

smarttools refresh

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

Installing Example Tools

Quick Install (All 28 Tools)

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 for all tool configurations.

Troubleshooting

"smarttools: command not found"

PATH is not configured. Add to your shell config:

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:

smarttools refresh

TUI doesn't start / looks broken

Install urwid:

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:

smarttools refresh

Python version mismatch

If you have multiple Python versions, ensure SmartTools uses the right one:

python3.11 -m pip install smarttools

Uninstalling

# 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

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
2. Browse example tools
3. Run smarttools ui to create your first tool