CmdForge/docs/INSTALL.md

Installation Guide

Complete installation instructions for CmdForge.

Quick Install

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:

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 CmdForge

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

With TUI and development dependencies:

pip install -e ".[dev]"

Step 3: Configure PATH

CmdForge 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. The easiest way is the interactive installer:

cmdforge providers install

This guides you through installing and authenticating providers.

Manual Installation

OpenCode (free tier available):

curl -fsSL https://opencode.ai/install | bash
source ~/.bashrc  # or start new shell
opencode  # Opens browser for sign-in

Claude CLI (pay-per-use):

npm install -g @anthropic-ai/claude-code
claude  # Opens browser for sign-in

Codex (pay-per-use):

npm install -g @openai/codex
codex  # Opens browser for sign-in

Gemini (free tier available):

npm install -g @google/gemini-cli
gemini  # Opens browser for Google sign-in

Ollama (free, runs locally):

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 for full provider setup instructions.

Step 5: Verify Installation

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

cmdforge refresh

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

Installing Example Tools

Quick Install (All 28 Tools)

python examples/install.py
cmdforge refresh

Manual Install

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

See EXAMPLES.md for all tool configurations.

Troubleshooting

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

"Permission denied" on tool execution

Refresh wrapper scripts:

cmdforge refresh

TUI doesn't start / looks broken

Install urwid:

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:

cmdforge refresh

Python version mismatch

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

python3.11 -m pip install cmdforge

Uninstalling

# 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

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