Move docs to project-docs symlink structure

- Docs now point to project-docs/docs/projects/cmdforge - Old docs preserved in olddocs/ - Updated .gitignore to ignore docs symlink 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
2026-01-06 22:26:39 -04:00
parent 1caa3454f0
commit 9fbe45244d
11 changed files with 3 additions and 0 deletions
@@ -0,0 +1,249 @@
+# 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 [email protected]
+```
+
+**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