250 lines
4.6 KiB
Markdown
250 lines
4.6 KiB
Markdown
# 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
|