rob/CmdForge
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation 2026-01-05

Browse Source
This commit is contained in:
rob
2026-01-05 04:05:42 -04:00
parent 32b77c3378
commit 737d8af3d8
3873 changed files with 344 additions and 722153 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.venv/lib/python3.12/site-packages/cmdforge-0.1.0.dist-info/METADATA
-648
View File
@@ -1,648 +0,0 @@
Metadata-Version: 2.4
Name: cmdforge
Version: 0.1.0
Summary: Build custom AI-powered CLI commands in YAML
Author: Rob
License: MIT
Project-URL: Homepage, https://cmdforge.brrd.tech
Project-URL: Documentation, https://cmdforge.brrd.tech/docs
Project-URL: Repository, https://gitea.brrd.tech/rob/CmdForge.git
Project-URL: Issues, https://gitea.brrd.tech/rob/CmdForge/issues
Keywords: ai,cli,tools,automation,llm,terminal,unix,pipe
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.28
Provides-Extra: tui
Requires-Dist: urwid>=2.1.0; extra == "tui"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: urwid>=2.1.0; extra == "dev"
Provides-Extra: registry
Requires-Dist: Flask>=2.3; extra == "registry"
Requires-Dist: argon2-cffi>=21.0; extra == "registry"
Requires-Dist: sentry-sdk[flask]>=1.0; extra == "registry"
Provides-Extra: all
Requires-Dist: urwid>=2.1.0; extra == "all"
Requires-Dist: Flask>=2.3; extra == "all"
Requires-Dist: argon2-cffi>=21.0; extra == "all"
Requires-Dist: sentry-sdk[flask]>=1.0; extra == "all"
# CmdForge
**A lightweight personal tool builder for AI-powered CLI commands.**
Turn any AI model into a Unix-style pipe command. Build once, use forever.
```bash
# Fix grammar in any file
echo "teh cat sat on teh mat" | fix-grammar
# Output: The cat sat on the mat
# Explain errors instantly
cat error.log | explain-error
# Generate commit messages
git diff --staged | commit-msg
# Extract data as validated JSON
echo "Price $49.99, SKU ABC-123" | json-extract --fields "price, sku"
# Output: {"price": 49.99, "sku": "ABC-123"}
```
## Why CmdForge?
- **Unix Philosophy** - Tools that do one thing well, composable with pipes
- **Provider Agnostic** - Works with Claude, GPT, Gemini, DeepSeek, local models
- **No Lock-in** - Your tools are YAML files, your prompts are yours
- **Multi-step Pipelines** - Chain AI prompts with Python code for validation
- **Meta-tools** - Tools can call other tools for powerful composition
- **12+ Providers Profiled** - We tested them so you don't have to
## Try It Now (60 seconds)
See CmdForge in action without installing anything on your system:
```bash
# Pull the container
docker pull gitea.brrd.tech/rob/cmdforge:latest
# Run it
docker run -it --rm gitea.brrd.tech/rob/cmdforge bash
# Inside the container - install OpenCode (includes free AI models)
cmdforge providers install # Select option 4, then 'y'
source ~/.bashrc
# Try it! This explains the README using the free Big Pickle model
cat README.md | eli5
```
That's it - you just used AI to explain itself. The `eli5` tool uses a free model by default, no sign-up required.
## Quick Start (Native Install)
For regular use, install natively:
```bash
# Clone and install
git clone https://gitea.brrd.tech/rob/CmdForge.git
cd CmdForge
pip install -e .
# Ensure ~/.local/bin is in PATH
export PATH="$HOME/.local/bin:$PATH"
# Install an AI provider (interactive guide)
cmdforge providers install
# Launch the UI
cmdforge ui
# Or create your first tool
cmdforge create summarize
```
## Installation
### Native Install
```bash
git clone https://gitea.brrd.tech/rob/CmdForge.git
cd CmdForge
pip install -e .
```
### With Development Dependencies
```bash
git clone https://gitea.brrd.tech/rob/CmdForge.git
cd CmdForge
pip install -e ".[dev]"
```
### Requirements
- Python 3.10+
- At least one AI CLI tool installed (see [Provider Setup](docs/PROVIDERS.md))
- Optional: `urwid` for the TUI (`pip install urwid`)
### Post-Install
Add to your `~/.bashrc` or `~/.zshrc`:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
Then refresh wrapper scripts:
```bash
cmdforge refresh
```
## Usage
### UI Mode (Recommended for Beginners)
```bash
cmdforge ui
```
Navigate with arrow keys, Tab, Enter, and mouse. Create tools visually with the built-in prompt editor.
### CLI Mode
```bash
cmdforge list # List all tools
cmdforge create mytool # Create new tool
cmdforge edit mytool # Edit in $EDITOR
cmdforge delete mytool # Delete tool
cmdforge run mytool # Run a tool
cmdforge test mytool # Test with mock provider
cmdforge check mytool # Check dependencies (meta-tools)
cmdforge refresh # Update executable wrappers
```
### Running Tools
Once created, tools work like any Unix command:
```bash
# Direct invocation
mytool -i input.txt -o output.txt
# Pipe input (most common)
cat file.txt | mytool
# With arguments
echo "hello" | translate --lang French
# Preview without calling AI
cat file.txt | mytool --dry-run
# Test with mock provider
cat file.txt | mytool --provider mock
```
### Composing Tools
CmdForge follows Unix philosophy: each tool does one thing well, and tools chain together for complex workflows.
```bash
# Chain CmdForge together
cat error.log | log-errors | summarize | translate --lang Spanish
# Code review pipeline: focus on changes, review, then summarize
git diff | diff-focus | review-code | tldr
# Extract data, convert format, analyze
cat report.pdf | json-extract --fields "revenue, costs, date" | json2csv | csv-insights
# Process text through multiple transformations
cat technical_doc.txt | simplify | fix-grammar | tone-shift --tone friendly
# Generate code, validate it, then explain what it does
echo "parse CSV and calculate averages" | code-validate | explain-code
```
**Mix with standard Unix tools:**
```bash
# Extract emails, deduplicate, count
cat inbox.txt | extract-emails | sort -u | wc -l
# Find errors in multiple logs, explain them
cat *.log | grep -i error | explain-error
# Generate changelog for specific author
git log --author="rob" --oneline | changelog > CHANGELOG.md
# Review only large files in a commit
git diff --stat | awk '$3 > 100 {print $1}' | xargs cat | review-code
```
**Build shell functions for common pipelines:**
```bash
# ~/.bashrc
quick-review() {
git diff "$@" | diff-focus | review-code --focus "bugs and security" | tldr
}
translate-doc() {
cat "$1" | summarize | translate --lang "$2"
}
# Usage: quick-review HEAD~3
# Usage: translate-doc manual.txt French
```
## Example Tools
CmdForge comes with 28 pre-built examples you can install:
### Text Processing
| Tool | Description | Example |
|------|-------------|---------|
| `summarize` | Condense documents | `cat article.txt \| summarize` |
| `translate` | Translate text | `echo "Hello" \| translate --lang Spanish` |
| `fix-grammar` | Fix spelling/grammar | `cat draft.txt \| fix-grammar` |
| `simplify` | Rewrite for clarity | `cat legal.txt \| simplify --level "5th grade"` |
| `tone-shift` | Change tone | `cat email.txt \| tone-shift --tone professional` |
| `eli5` | Explain like I'm 5 | `cat quantum.txt \| eli5` |
| `tldr` | One-line summary | `cat readme.txt \| tldr` |
| `expand` | Expand bullet points | `cat notes.txt \| expand` |
### Developer Tools
| Tool | Description | Example |
|------|-------------|---------|
| `explain-error` | Explain stack traces | `cat error.log \| explain-error` |
| `explain-code` | Explain what code does | `cat script.py \| explain-code` |
| `review-code` | Quick code review | `cat pr.diff \| review-code --focus security` |
| `gen-tests` | Generate unit tests | `cat module.py \| gen-tests --framework pytest` |
| `docstring` | Add docstrings | `cat functions.py \| docstring` |
| `commit-msg` | Generate commit message | `git diff --staged \| commit-msg` |
### Data Tools
| Tool | Description | Example |
|------|-------------|---------|
| `json-extract` | Extract as validated JSON | `cat text.txt \| json-extract --fields "name, email"` |
| `json2csv` | Convert JSON to CSV | `cat data.json \| json2csv` |
| `extract-emails` | Extract email addresses | `cat page.html \| extract-emails` |
| `extract-contacts` | Extract contacts as CSV | `cat notes.txt \| extract-contacts` |
| `sql-from-text` | Natural language to SQL | `echo "get active users" \| sql-from-text` |
| `safe-sql` | SQL with safety checks | `echo "delete old records" \| safe-sql` |
| `parse-log` | Analyze log files | `cat app.log \| parse-log --focus errors` |
| `csv-insights` | Analyze CSV data | `cat sales.csv \| csv-insights --question "trends?"` |
### Advanced Multi-Step Tools
| Tool | Description | Pattern |
|------|-------------|---------|
| `log-errors` | Extract & explain errors from huge logs | Code→AI |
| `diff-focus` | Review only added lines | Code→AI |
| `changelog` | Git log to formatted changelog | Code→AI→Code |
| `code-validate` | Generate syntax-checked Python | AI→Code |
### Install Example Tools
```bash
# Run the example installer (from the CmdForge directory)
python examples/install.py
cmdforge refresh
```
## Providers
CmdForge works with any AI CLI tool. We've profiled 12 providers:
| Provider | Speed | Accuracy | Cost | Best For |
|----------|-------|----------|------|----------|
| `opencode-deepseek` | 13s | 4/4 | Cheap | **Best value** - daily use |
| `opencode-pickle` | 13s | 4/4 | FREE | **Best free** - accurate |
| `claude-haiku` | 14s | 4/4 | Paid | Fast + accurate |
| `codex` | 14s | 4/4 | Paid | Reliable |
| `claude-opus` | 18s | 4/4 | $$$ | Highest quality |
| `gemini` | 91s | 3/4 | Paid | Large docs (1M tokens) |
See [docs/PROVIDERS.md](docs/PROVIDERS.md) for setup instructions.
## Tool Anatomy
A tool is a YAML config file in `~/.cmdforge/<name>/config.yaml`:
```yaml
name: summarize
description: Condense documents to key points
category: Text # Optional: Text, Developer, Data, or Other
arguments:
- flag: --length
variable: length
default: "3-5 bullet points"
steps:
- type: prompt
prompt: |
Summarize this text into {length}:
{input}
provider: opencode-pickle
output_var: response
output: "{response}"
```
### Categories
Tools can be organized into categories for easier navigation in the UI:
| Category | Description |
|----------|-------------|
| `Text` | Text processing (summarize, translate, grammar) |
| `Developer` | Dev tools (explain-error, gen-tests, commit-msg) |
| `Data` | Data extraction and conversion (json-extract, csv) |
| `Other` | Default for uncategorized tools |
### Multi-Step Tools
Chain AI prompts with Python code for powerful workflows:
```yaml
name: json-extract
description: Extract data as validated JSON
steps:
# Step 1: AI extracts data
- type: prompt
prompt: "Extract {fields} as JSON from: {input}"
provider: opencode-deepseek
output_var: raw_json
# Step 2: Code validates JSON
- type: code
code: |
import json
try:
parsed = json.loads(raw_json)
validated = json.dumps(parsed, indent=2)
except:
validated = "ERROR: Invalid JSON"
output_var: validated
output: "{validated}"
```
### Meta-Tools (Tools Calling Tools)
Tools can call other tools as steps, enabling powerful composition:
```yaml
name: summarize-and-translate
description: Summarize text then translate the summary
dependencies:
- official/summarize
- official/translate
steps:
- type: tool
tool: official/summarize
input: "{input}"
args:
max_words: "100"
output_var: summary
- type: tool
tool: official/translate
input: "{summary}"
args:
target_language: "{language}"
output_var: translated
output: "{translated}"
```
Check dependencies before running: `cmdforge check my-meta-tool`
See [docs/META_TOOLS.md](docs/META_TOOLS.md) for full documentation.
### Variables
| Variable | Description |
|----------|-------------|
| `{input}` | The piped/file input |
| `{argname}` | Custom argument value |
| `{output_var}` | Output from previous step (prompt, code, or tool) |
## Shell Integration
### Git Hooks
```bash
# .git/hooks/prepare-commit-msg
#!/bin/bash
git diff --cached | commit-msg > "$1"
```
### Aliases
```bash
# ~/.bashrc
alias gc='git diff --staged | commit-msg'
alias wtf='explain-error'
alias fixme='fix-grammar'
```
### Vim Integration
```vim
" Fix grammar in selection
vnoremap <leader>fg :!fix-grammar<CR>
" Explain selected code
vnoremap <leader>ec :!explain-code<CR>
```
## UI Navigation
| Action | Keys |
|--------|------|
| Cycle sections | `Tab` |
| Go back | `Escape` |
| Select | `Enter` or click |
| Navigate | Arrow keys |
| **Scroll content** | Mouse wheel |
| **Scroll up** | Click top of scrollbar |
| **Scroll down** | Click bottom of scrollbar |
| **Page up/down** | Click middle of scrollbar |
| **Select text** | `Shift` + mouse drag |
| **Copy** | Terminal native (with Shift) |
| **Paste** | `Ctrl+Shift+V` |
| **Undo** (code editor) | `Alt+U` |
| **Redo** (code editor) | `Alt+R` |
**Tips:**
- Hold `Shift` while using mouse for terminal-native text selection.
- Code/Prompt editors have DOS-style scrollbars with `▲` and `▼` arrow buttons.
- In step dialogs, use `Tab` to cycle between File, Editor, and Output fields.
- The code editor supports undo/redo (up to 50 states) with `Alt+U` and `Alt+R`.
- Use the `$EDITOR` button to open code or prompts in your external editor.
## AI-Assisted Code Generation
When adding or editing a **Code Step**, the dialog includes an AI assist panel:
```
┌─ Code ─────────────┐ ┌─ AI Assisted Auto-adjust ─────────────┐
│ result = input... │ │ Provider: [opencode-deepseek] [▼] │
│ │ │ ┌─ Prompt ──────────────────────────┐ │
│ │ │ │ Modify this code to... │ │
│ │ │ │ {code} │ │
│ │ │ └──────────────────────────────────┘ │
│ │ │ ┌─ Output & Feedback ───────────────┐ │
│ │ │ │ ✓ Code updated successfully! │ │
│ │ │ └──────────────────────────────────┘ │
│ │ │ < Auto-adjust > │
└────────────────────┘ └───────────────────────────────────────┘
```
- **Provider**: Select any configured AI provider
- **Prompt**: Fully editable template - use `{code}` placeholder for current code
- **Output**: Shows status, success/error messages, and provider feedback
- **Auto-adjust**: Sends prompt to AI and replaces code with response
This lets you generate or modify Python code using AI directly within the tool builder.
## Philosophy
CmdForge is built on **Unix philosophy**:
1. **Do one thing well** - Each tool solves one problem. `summarize` summarizes. `translate` translates. No bloated mega-tools.
2. **Compose freely** - Tools read stdin, write stdout. Chain them: `cat doc.txt | summarize | translate --lang French`
3. **Text is the interface** - No proprietary formats. Pipe text in, get text out. Works with `grep`, `awk`, `sed`, and every other Unix tool.
4. **You own everything** - Tools are YAML files. Prompts are plain text. No vendor lock-in, no cloud dependency for your tool definitions.
5. **Swap parts freely** - Change AI providers per-tool or per-run. Today's best model might not be tomorrow's.
## Contributing
```bash
git clone https://gitea.brrd.tech/rob/cmdforge.git
cd cmdforge
pip install -e ".[dev]"
pytest
```
## Support
If CmdForge saves you time, consider supporting the project:
**Bitcoin:** `3KeLqGv2Xo8jGYkqA1i68a6nXwgQnuJoza`
**Questions?** [email protected]
## License
MIT - Use it, modify it, share it.
## Docker
### Pre-built Container (Fastest)
Pull and run the pre-built image directly:
```bash
# Pull from registry
docker pull gitea.brrd.tech/rob/cmdforge:latest
# Run CmdForge
docker run -it --rm gitea.brrd.tech/rob/cmdforge cmdforge --help
# List available tools
docker run -it --rm gitea.brrd.tech/rob/cmdforge cmdforge list
# Interactive shell
docker run -it --rm gitea.brrd.tech/rob/cmdforge bash
```
### Build from Source
Alternatively, build the container yourself:
```bash
# Clone the repo
git clone https://gitea.brrd.tech/rob/CmdForge.git
cd CmdForge
# Build the container
docker-compose build
# Run tests
docker-compose run --rm test
# Use the CLI
docker-compose run --rm cli cmdforge list
# Interactive shell
docker-compose run --rm shell
```
### Installing AI Providers in Docker
AI providers require browser-based authentication. You need display access for the browser to open.
**Using the pre-built container:**
```bash
# Allow Docker to access your display (Linux)
xhost +local:docker
# Run with display access and persistent storage
docker run -it --rm \
-e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-v cmdforge-data:/root/.cmdforge \
--network host \
gitea.brrd.tech/rob/cmdforge bash
# Inside the container:
cmdforge providers install
```
**Using docker-compose (build from source):**
```bash
xhost +local:docker
docker-compose run --rm setup
# Inside the container:
cmdforge providers install
```
**After installing a provider:**
```bash
# Test the provider works
cmdforge providers test claude
```
**Available Providers:**
| # | Provider | Cost | Notes |
|---|----------|------|-------|
| 1 | Claude | Pay-per-use | Anthropic account |
| 2 | Codex | Pay-per-use | OpenAI account |
| 3 | Gemini | Free tier | Google account |
| 4 | OpenCode | Free tier | Multiple models |
| 5 | Ollama | FREE | Local, no internet |
## Links
### User Documentation
- [Installation Guide](docs/INSTALL.md)
- [Provider Setup](docs/PROVIDERS.md)
- [Example Tools](docs/EXAMPLES.md)
- [User Wiki](wiki/Home.md)
### Developer Documentation
- [Project Overview](docs/PROJECT.md) - Start here to understand the codebase
- [Design Document](docs/DESIGN.md)
- [Meta-Tools Design](docs/META_TOOLS.md) - Tools that call other tools
- [Registry API Design](docs/REGISTRY.md)
- [Web UI Design](docs/WEB_UI.md)
- [Deployment Guide](docs/DEPLOYMENT.md)
- [Architecture Diagrams](docs/diagrams/)