1137 lines
34 KiB
Markdown
1137 lines
34 KiB
Markdown
# 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
|
|
# Install the application with MCP and interactive-provider support
|
|
pipx install "cmdforge[mcp,pty]"
|
|
|
|
# Ensure ~/.local/bin is in PATH
|
|
export PATH="$HOME/.local/bin:$PATH"
|
|
|
|
# Discover AI CLIs, API keys, and Ollama models already on this machine
|
|
cmdforge providers discover --add
|
|
|
|
# Launch the GUI
|
|
cmdforge
|
|
|
|
# Or create your first tool via CLI
|
|
cmdforge create summarize
|
|
```
|
|
|
|
## Installation
|
|
|
|
### From PyPI
|
|
|
|
```bash
|
|
pipx install "cmdforge[mcp,pty]"
|
|
```
|
|
|
|
Or install into an active virtual environment:
|
|
|
|
```bash
|
|
python -m pip install "cmdforge[mcp,pty]"
|
|
```
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone https://gitea.brrd.tech/rob/CmdForge.git
|
|
cd CmdForge
|
|
python -m pip install -e ".[mcp,pty]"
|
|
```
|
|
|
|
### With Development Dependencies
|
|
|
|
```bash
|
|
git clone https://gitea.brrd.tech/rob/CmdForge.git
|
|
cd CmdForge
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### Requirements
|
|
|
|
- Python 3.10+
|
|
- A configured provider for live AI calls; the built-in mock works without one
|
|
- PySide6 (included automatically - requires display server on Linux)
|
|
|
|
### Post-Install
|
|
|
|
Add to your `~/.bashrc` or `~/.zshrc`:
|
|
|
|
```bash
|
|
export PATH="$HOME/.local/bin:$PATH"
|
|
```
|
|
|
|
Then refresh wrapper scripts:
|
|
|
|
```bash
|
|
cmdforge refresh
|
|
```
|
|
|
|
## Usage
|
|
|
|
### GUI Mode (Recommended for Beginners)
|
|
|
|
```bash
|
|
cmdforge
|
|
```
|
|
|
|
Opens the graphical interface where you can create and manage tools visually. Features include:
|
|
- **My Tools** - Browse, create, edit, and delete tools organized by category
|
|
- **Registry** - Search and install community tools from the CmdForge registry
|
|
- **Providers** - Manage AI provider configurations
|
|
- **Reuse & Discovery** - Compare similar tools and preview safe extraction of reusable steps
|
|
- **Scoped saving** - Save a new tool to the current project or your global tool collection
|
|
|
|
|
|
|
|
### CLI Mode
|
|
|
|
```bash
|
|
# Tool Management
|
|
cmdforge list --filter summarize # Filter installed tools for humans
|
|
cmdforge list --json --filter summarize --limit 10 # Compact agent catalog
|
|
cmdforge list --json --full --limit 1 # Explicitly include prompts/code
|
|
cmdforge create mytool # Create a global tool
|
|
cmdforge create mytool --project # Versionable ./.cmdforge tool
|
|
echo "Build a bounded classifier" | forge-tool --name classify --project
|
|
cmdforge edit mytool # Edit in $EDITOR
|
|
cmdforge delete mytool # Delete tool
|
|
cmdforge run mytool # Run a tool
|
|
cat document.txt | cmdforge run-once "Summarize this:\n\n{input}"
|
|
cmdforge run private-tool --provider ollama --no-fallback \
|
|
--require-local --data-classification private --result-envelope json
|
|
cmdforge test mytool # Test with mock provider
|
|
cmdforge check mytool # Check dependencies (meta-tools)
|
|
cmdforge inspect mytool # Preflight, contract proposals, safe conformance tests
|
|
cmdforge inspect mytool --registry # Also find similar registry tools
|
|
cmdforge inspect mytool --save-baseline # Approve passing evidence for regression checks
|
|
cmdforge refresh # Update executable wrappers
|
|
cmdforge docs mytool # View/create tool documentation
|
|
|
|
# Registry
|
|
cmdforge registry search "keyword" # Search for tools
|
|
cmdforge registry install owner/tool # Install a tool
|
|
cmdforge registry publish mytool # Preflight, confirm, then publish
|
|
cmdforge registry publish mytool --dry-run # Preflight without publishing
|
|
cmdforge registry status # Check moderation status
|
|
cmdforge registry my-tools # List your published tools
|
|
|
|
# Collections (curated tool bundles)
|
|
cmdforge collections list # List registry collections
|
|
cmdforge collections list --local # List your local collections
|
|
cmdforge collections info starter # View collection details
|
|
cmdforge collections install starter # Install all tools in a collection
|
|
cmdforge collections create my-tools # Create local collection
|
|
cmdforge collections show my-tools # View local collection
|
|
cmdforge collections add my-tools summarize # Add tool to collection
|
|
cmdforge collections remove my-tools summarize # Remove tool
|
|
cmdforge collections delete my-tools # Delete local collection
|
|
cmdforge collections publish my-tools # Publish to registry
|
|
cmdforge collections status my-tools # Check tool statuses
|
|
|
|
# Project Dependencies
|
|
cmdforge init # Create cmdforge.yaml manifest
|
|
cmdforge add owner/tool # Add tool as dependency
|
|
cmdforge install # Install all dependencies
|
|
cmdforge deps # Check dependency status
|
|
|
|
# Tool Settings
|
|
cmdforge settings mytool show # View tool settings
|
|
cmdforge settings mytool edit # Edit in $EDITOR
|
|
cmdforge settings mytool reset # Reset to defaults
|
|
cmdforge settings mytool diff # Show changes from defaults
|
|
|
|
# Configuration
|
|
cmdforge config show # Show current config
|
|
cmdforge config connect username # Connect to registry account
|
|
cmdforge config disconnect # Disconnect from registry
|
|
|
|
# Private, local pipeline suggestions (disabled by default)
|
|
cmdforge usage enable # Begin recording tool names in shell pipes
|
|
cmdforge usage suggestions # Show frequent pipelines
|
|
cmdforge usage clear # Delete all local usage history
|
|
|
|
# Model Context Protocol (optional: python -m pip install "cmdforge[mcp]")
|
|
cmdforge mcp add local --command npx --arg=-y --arg @scope/server
|
|
cmdforge mcp add remote --transport streamable-http --url https://example.com/mcp
|
|
cmdforge mcp connect remote
|
|
cmdforge mcp serve # Expose approved tools over stdio
|
|
cmdforge mcp serve --transport streamable-http # Loopback-only HTTP by default
|
|
|
|
# Connect a coding agent and add a managed project policy
|
|
cmdforge mcp configure codex --dry-run
|
|
cmdforge mcp configure codex
|
|
cmdforge mcp configure claude-code --scope project
|
|
```
|
|
|
|
`mcp configure` registers CmdForge's stdio server through the host's own CLI
|
|
and adds an idempotent managed block to `AGENTS.md` (Codex) or `CLAUDE.md`
|
|
(Claude Code). It preserves all text outside that block. Preview with
|
|
`--dry-run`, skip the policy with `--no-policy`, or deliberately replace an
|
|
existing registration with `--force`. Setup never broadens the MCP exposure
|
|
allowlist: review tools and add their names under `server.expose` in
|
|
`~/.cmdforge/mcp.yaml`.
|
|
|
|
`cf` searches the public registry when no local tool matches. Registry results
|
|
show available relevance and quality evidence and install on selection.
|
|
When local pipeline discovery is explicitly enabled, `cf` also suggests
|
|
frequently repeated pipe pairs. Only tool names, anonymous pipe identifiers,
|
|
counts, and timestamps are kept in `~/.cmdforge/usage.json`; command arguments
|
|
and input/output content are never recorded or transmitted.
|
|
|
|
### AI Assistant Workflow
|
|
|
|
For coding assistants, use CmdForge when an installed or registry tool matches
|
|
the task; direct application APIs remain appropriate when the API is part of
|
|
the product being built.
|
|
|
|
```bash
|
|
# 1. Discover a compact local contract without exposing prompt/code bodies
|
|
cmdforge list --json --filter "commit message" --limit 10
|
|
|
|
# 2. Search remotely if no local tool fits
|
|
cmdforge registry search "generate commit message" --json --limit 5
|
|
|
|
# 3. Use a one-shot provider call for genuinely ad-hoc work
|
|
git diff --staged | cmdforge run-once "Write a commit message for:\n\n{input}"
|
|
|
|
# 4. Promote repeated work into a permanent, reviewable tool
|
|
echo "Create a conventional commit-message tool" | forge-tool --name commit-msg
|
|
```
|
|
|
|
`run-once` honors `cmdforge config set default_provider NAME`, then selects an
|
|
available configured provider when no default is set. Configure CmdForge as an
|
|
MCP server when the assistant supports MCP so approved tools appear in its
|
|
native tool catalog. `cmdforge mcp configure codex` and
|
|
`cmdforge mcp configure claude-code` automate the host registration and add
|
|
the discovery policy shown above to the host's project instruction file.
|
|
|
|
### 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 [Provider Setup](docs/reference/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 [Meta-Tools Design](docs/reference/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) |
|
|
| `{settings.key}` | Value from tool's settings file (scalars only) |
|
|
|
|
### Tool Settings
|
|
|
|
Tools can ship with configurable settings that users can customize without editing the tool itself:
|
|
|
|
```
|
|
~/.cmdforge/tts/
|
|
├── config.yaml # Tool definition (published)
|
|
├── defaults.yaml # Default settings (published with tool)
|
|
├── settings.yaml # User's customized settings (auto-created, not published)
|
|
└── README.md # Documentation
|
|
```
|
|
|
|
**Creating a tool with settings:**
|
|
|
|
```yaml
|
|
# defaults.yaml - ships with your tool
|
|
backend: piper
|
|
endpoint: http://localhost:5001
|
|
api_key: '' # User fills in their own key
|
|
voice: default
|
|
```
|
|
|
|
**Using settings in steps:**
|
|
|
|
```yaml
|
|
# In a prompt step (top-level scalars only)
|
|
prompt: "Using {settings.backend} at {settings.endpoint}"
|
|
|
|
# In a code step (full access)
|
|
code: |
|
|
endpoint = settings.get('endpoint')
|
|
api_key = settings['api_key']
|
|
if not api_key:
|
|
raise ValueError("Please set api_key in settings")
|
|
```
|
|
|
|
**Managing settings via CLI:**
|
|
|
|
```bash
|
|
cmdforge settings tts show # View current settings
|
|
cmdforge settings tts edit # Edit in $EDITOR
|
|
cmdforge settings tts reset # Reset to defaults
|
|
cmdforge settings tts diff # Show changes from defaults
|
|
```
|
|
|
|
Settings are fully optional - tools without a `defaults.yaml` work exactly as before.
|
|
|
|
## Project Dependencies
|
|
|
|
For projects that use multiple CmdForge tools, you can declare dependencies in a `cmdforge.yaml` manifest:
|
|
|
|
```yaml
|
|
# cmdforge.yaml
|
|
name: my-project
|
|
description: My awesome project
|
|
dependencies:
|
|
- official/summarize
|
|
- official/translate
|
|
- myuser/custom-tool@^1.0.0
|
|
```
|
|
|
|
### Managing Dependencies
|
|
|
|
```bash
|
|
# Initialize a new manifest
|
|
cmdforge init
|
|
|
|
# Add a dependency
|
|
cmdforge add official/summarize
|
|
cmdforge add myuser/tool@^2.0.0 # With version constraint
|
|
|
|
# Install all dependencies (including transitive)
|
|
cmdforge install
|
|
|
|
# Check dependency status
|
|
cmdforge deps
|
|
|
|
# Show full dependency tree
|
|
cmdforge deps tree
|
|
```
|
|
|
|
### Reproducible Installs with Lock Files
|
|
|
|
Lock files ensure identical tool versions across machines and over time:
|
|
|
|
```bash
|
|
# Generate lock file after installing
|
|
cmdforge lock
|
|
|
|
# Install exact versions from lock (reproducible)
|
|
cmdforge install # Uses lock file if present
|
|
|
|
# CI/CD: Fail if lock is missing or stale
|
|
cmdforge install --frozen # Requires lock file
|
|
cmdforge install --strict-frozen # Requires lock + manifest match
|
|
|
|
# Verify installed tools match lock
|
|
cmdforge verify
|
|
|
|
# Preview what would be installed
|
|
cmdforge install --dry-run
|
|
|
|
# Ignore lock and resolve fresh
|
|
cmdforge install --ignore-lock
|
|
```
|
|
|
|
### Version Constraints
|
|
|
|
CmdForge supports semantic versioning constraints:
|
|
|
|
| Constraint | Meaning | Example |
|
|
|------------|---------|---------|
|
|
| `*` | Any version | `official/summarize` |
|
|
| `^1.2.3` | Compatible (>=1.2.3 <2.0.0) | `tool@^1.2.3` |
|
|
| `~1.2.3` | Approximately (>=1.2.3 <1.3.0) | `tool@~1.2.3` |
|
|
| `>=1.0.0` | Greater or equal | `tool@>=1.0.0` |
|
|
| `1.0.0` | Exact version | `tool@1.0.0` |
|
|
|
|
This ensures all required tools are available before running your project's scripts.
|
|
|
|
## Collections
|
|
|
|
Collections are curated bundles of related tools. Install an entire workflow with one command.
|
|
|
|
### Registry Collections
|
|
|
|
Browse and install collections from the CmdForge registry:
|
|
|
|
```bash
|
|
# List available collections from registry
|
|
cmdforge collections list
|
|
|
|
# View what's in a collection
|
|
cmdforge collections info starter
|
|
# Output:
|
|
# starter - Essential tools for getting started
|
|
# Tools: summarize, translate, fix-grammar, explain-error, commit-msg
|
|
# Total: 5 tools
|
|
|
|
# Install all tools in a collection
|
|
cmdforge collections install starter
|
|
```
|
|
|
|
### Local Collections
|
|
|
|
Create and manage your own collections locally:
|
|
|
|
```bash
|
|
# List your local collections
|
|
cmdforge collections list --local
|
|
|
|
# Create a new local collection
|
|
cmdforge collections create my-toolkit
|
|
|
|
# View collection details
|
|
cmdforge collections show my-toolkit
|
|
|
|
# Add tools to the collection
|
|
cmdforge collections add my-toolkit summarize
|
|
cmdforge collections add my-toolkit official/translate
|
|
|
|
# Remove tools from the collection
|
|
cmdforge collections remove my-toolkit summarize
|
|
|
|
# Delete a collection
|
|
cmdforge collections delete my-toolkit
|
|
```
|
|
|
|
### Publishing Collections
|
|
|
|
Share your collections with the community:
|
|
|
|
```bash
|
|
# Check collection status before publishing
|
|
cmdforge collections status my-toolkit
|
|
# Shows: tool visibility, approval status, any issues
|
|
|
|
# Publish to registry (requires account)
|
|
cmdforge collections publish my-toolkit
|
|
|
|
# Dry run to see what would be published
|
|
cmdforge collections publish my-toolkit --dry-run
|
|
|
|
# Force publish even with warnings
|
|
cmdforge collections publish my-toolkit --force
|
|
|
|
# Continue publishing after fixing issues
|
|
cmdforge collections publish my-toolkit --continue
|
|
```
|
|
|
|
**Publishing requirements:**
|
|
- All tools must be public (not private visibility)
|
|
- All tools must have an approved version in the registry
|
|
- Local tools will be prefixed with your username (e.g., `summarize` → `yourname/summarize`)
|
|
|
|
### Available Registry Collections
|
|
|
|
| Collection | Description | Tools |
|
|
|------------|-------------|-------|
|
|
| `starter` | Essential tools for beginners | 5 |
|
|
| `developer` | Code review and development | 8 |
|
|
| `writer` | Writing and editing tools | 6 |
|
|
| `data` | Data extraction and conversion | 7 |
|
|
|
|
## Registry
|
|
|
|
The CmdForge Registry at [cmdforge.brrd.tech](https://cmdforge.brrd.tech) hosts community tools.
|
|
|
|
### Searching Tools
|
|
|
|
```bash
|
|
# Basic search
|
|
cmdforge registry search "summarize"
|
|
|
|
# Filter by category
|
|
cmdforge registry search --category Developer
|
|
|
|
# Sort by popularity
|
|
cmdforge registry search --sort downloads
|
|
|
|
# Show only new tools (last 7 days)
|
|
cmdforge registry search --new
|
|
|
|
# Advanced filters
|
|
cmdforge registry search --owner official --min-downloads 100
|
|
```
|
|
|
|
### Publishing Tools
|
|
|
|
```bash
|
|
# Connect your account (opens browser for authentication)
|
|
cmdforge config connect yourusername
|
|
|
|
# Create an Ed25519 release key and register its public half
|
|
cmdforge registry signing-key init
|
|
|
|
# Publish a tool
|
|
cmdforge registry publish mytool
|
|
|
|
# Check moderation status
|
|
cmdforge registry status
|
|
# Output:
|
|
# mytool: pending (submitted 2 hours ago)
|
|
# other-tool: approved
|
|
|
|
# Sync moderation feedback to your local tool
|
|
cmdforge registry status --sync
|
|
```
|
|
|
|
Published tools go through moderation before appearing publicly. You'll receive feedback if changes are requested.
|
|
Once a signing key is registered, publishing signs the transitive content
|
|
identity automatically. The registry rejects unsigned or invalid releases and
|
|
clients verify the signature before installing. The private key remains in
|
|
`~/.cmdforge/release-signing-key.json` with `0600` permissions.
|
|
|
|
### Prompt Optimization
|
|
|
|
Generate local deterministic prompt variations without contacting a provider:
|
|
|
|
```bash
|
|
cmdforge optimize summarize -n 5
|
|
```
|
|
|
|
Structural contract checks cannot rank prompt meaning, so CmdForge will not
|
|
claim a winning variation unless explicit behavioral cases are supplied:
|
|
|
|
```json
|
|
[
|
|
{"input": "A long input", "contains": "summary"},
|
|
{"input": "Another input", "expected": {"result": "expected value"}}
|
|
]
|
|
```
|
|
|
|
```bash
|
|
cmdforge optimize summarize --behavior-tests behavior.json \
|
|
--test-provider opencode-pickle
|
|
```
|
|
|
|
Behavior tests execute every candidate and may incur provider cost. Use
|
|
`--provider NAME` separately when you explicitly want a provider to generate a
|
|
rephrased candidate.
|
|
|
|
### Community Improvements
|
|
|
|
```bash
|
|
cmdforge registry improve owner/tool 1.0.0 0 proposed-prompt.txt \
|
|
--rationale "Clearer output requirement"
|
|
cmdforge registry review-improvement 42 approve --notes "Tests pass"
|
|
# Apply the approved text, bump the tool version, then publish it:
|
|
cmdforge registry publish mytool --improvement-id 42
|
|
```
|
|
|
|
Submissions are auto-tested before review. Contributor credit and the
|
|
`optimized`/`community-reviewed` badges are awarded only when a published
|
|
version actually contains the approved change.
|
|
|
|
### Tool Documentation
|
|
|
|
Each tool can have its own README:
|
|
|
|
```bash
|
|
# View tool documentation
|
|
cmdforge docs mytool
|
|
|
|
# Create/edit documentation (opens in $EDITOR)
|
|
cmdforge docs mytool --edit
|
|
```
|
|
|
|
The documentation is stored as `README.md` in the tool's directory (`~/.cmdforge/mytool/README.md`).
|
|
|
|
## 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>
|
|
```
|
|
|
|
## GUI Features
|
|
|
|
The graphical interface provides a modern desktop experience:
|
|
|
|
### My Tools Page
|
|
- View all your tools organized by category (Text, Developer, Data, Other)
|
|
- Double-click a tool to edit it
|
|
- Create new tools with the built-in Tool Builder
|
|
- Connect to the registry to publish your tools
|
|
- **Rate & review** registry-installed tools with a 5-star rating system
|
|
- **Report issues** on registry tools (bug, compatibility, security)
|
|
|
|
### Collections Page
|
|
- **Local Collections**: Create and manage your own tool bundles
|
|
- Create new collections with display name and description
|
|
- Add/remove tools from collections
|
|
- View collection details and tool lists
|
|
- **Registry Collections**: Browse collections from the registry
|
|
- Search and filter available collections
|
|
- View collection contents before installing
|
|
- One-click install for all tools in a collection
|
|
- **Publish Collections**: Share your collections with the community
|
|
- Automatic tool resolution (local names → registry references)
|
|
- Visibility and approval status checks
|
|
- Options to publish tools first, skip unpublished, or cancel
|
|
|
|
### Tool Builder
|
|
- Visual form for creating and editing tools
|
|
- Reuse & Discovery panel with asynchronous registry similarity results,
|
|
exact local reuse evidence, and opt-in pipeline suggestions
|
|
- Extraction creates a separate tool only after showing a unified diff; the
|
|
current draft is never rewritten automatically
|
|
- Add arguments with flags and default values
|
|
- Add prompt steps (AI calls) with profile selection
|
|
- Add code steps with **AI-assisted code generation**:
|
|
- Split view: code editor + AI assist panel
|
|
- Describe what you want and generate Python code
|
|
- Shows available variables from arguments and previous steps
|
|
- Automatic markdown fence stripping from AI responses
|
|
|
|
### Registry Browser
|
|
- **Browse all** tools on page load (no search required)
|
|
- **Search** by name, description, or keyword
|
|
- **Filter** by category (Text, Developer, Data, Other)
|
|
- **Sort** by popularity, rating, newest, or name
|
|
- **Star ratings** displayed in results and details
|
|
- **Clickable tags** to filter by tag
|
|
- **Installed indicator** (✓) shows which tools you have
|
|
- **Update available** (↑) when newer version exists
|
|
- **Pagination** for browsing large result sets
|
|
- **Publisher info** showing reputation and total downloads
|
|
|
|
### Provider Management
|
|
- Add and configure AI providers
|
|
- Test provider connectivity
|
|
- Set default providers for new tools
|
|
|
|
### Profiles (AI Personas)
|
|
- **Built-in profiles**: Comedian, Technical Writer, Teacher, Concise, Creative, Code Reviewer, Analyst
|
|
- **Custom profiles**: Create your own personas with custom system prompts
|
|
- **Profile selector**: Choose a profile when adding prompt steps to tools
|
|
- **Automatic injection**: Profile system prompts are prepended to your prompts during execution
|
|
|
|
### Keyboard Shortcuts
|
|
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Ctrl+N` | Create new tool |
|
|
| `Ctrl+S` | Save tool (in builder) |
|
|
| `Ctrl+R` | Refresh current page |
|
|
| `Ctrl+1` | Go to My Tools |
|
|
| `Ctrl+2` | Go to Registry |
|
|
| `Ctrl+3` | Go to Collections |
|
|
| `Ctrl+4` | Go to Providers |
|
|
| `Ctrl+5` | Go to Profiles |
|
|
| `Escape` | Close tool builder |
|
|
| `Ctrl+Q` | Quit application |
|
|
|
|
## Multi-Step Tool Patterns
|
|
|
|
CmdForge supports powerful multi-step workflows combining AI and code:
|
|
|
|
### Code → AI
|
|
Extract or transform data with Python, then pass to AI:
|
|
```yaml
|
|
steps:
|
|
- type: code
|
|
code: |
|
|
# Extract just the error lines
|
|
errors = [l for l in input_text.split('\n') if 'error' in l.lower()]
|
|
result = '\n'.join(errors[-10:]) # Last 10 errors
|
|
output_var: errors
|
|
- type: prompt
|
|
prompt: "Explain these errors:\n{errors}"
|
|
output_var: explanation
|
|
```
|
|
|
|
### AI → Code
|
|
Generate content with AI, then validate/process with Python:
|
|
```yaml
|
|
steps:
|
|
- type: prompt
|
|
prompt: "Generate Python code to: {input}"
|
|
output_var: generated
|
|
- type: code
|
|
code: |
|
|
import ast
|
|
try:
|
|
ast.parse(generated) # Syntax check
|
|
result = generated
|
|
except SyntaxError as e:
|
|
result = f"# Syntax Error: {e}\n{generated}"
|
|
output_var: validated
|
|
```
|
|
|
|
## 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?** robdickson444@hotmail.com
|
|
|
|
## License
|
|
|
|
MIT - Use it, modify it, share it.
|
|
|
|
## Docker
|
|
|
|
### Pre-installed Container (Recommended)
|
|
|
|
Ready-to-use container with CmdForge and 27 example tools pre-installed:
|
|
|
|
```bash
|
|
# Build from source
|
|
docker build -f Dockerfile.ready -t cmdforge-ready .
|
|
|
|
# Run interactively
|
|
docker run -it --rm cmdforge-ready
|
|
|
|
# With persistent storage (keeps your tools between runs)
|
|
docker run -it --rm -v cmdforge-data:/home/user/.cmdforge cmdforge-ready
|
|
```
|
|
|
|
Inside the container, CmdForge is ready to use:
|
|
```bash
|
|
cmdforge list # See 27 pre-installed tools
|
|
cmdforge # Launch the GUI (requires display)
|
|
cmdforge run summarize # Run a tool
|
|
```
|
|
|
|
### Test Installation Container
|
|
|
|
Simulates a fresh computer for testing the installation process:
|
|
|
|
```bash
|
|
# Build the test container
|
|
docker build -f Dockerfile.test-install -t cmdforge-test-install .
|
|
|
|
# Run interactively
|
|
docker run -it --rm cmdforge-test-install
|
|
|
|
# Inside the container - run the installer
|
|
cd ~/CmdForge
|
|
./install.sh
|
|
```
|
|
|
|
### Interactive Installer
|
|
|
|
The `install.sh` script provides guided installation:
|
|
|
|
```bash
|
|
./install.sh # Full interactive install
|
|
./install.sh --yes # Non-interactive (accept defaults)
|
|
./install.sh --no-venv # Install without virtual environment
|
|
./install.sh --no-examples # Skip installing example tools
|
|
```
|
|
|
|
Features:
|
|
- Creates virtual environment at `~/.cmdforge-venv`
|
|
- Configures PATH in your shell config (bash/zsh/fish)
|
|
- Optionally installs 27 example tools
|
|
- Works on macOS and Linux
|
|
|
|
### Legacy Container
|
|
|
|
The original docker-compose setup still works:
|
|
|
|
```bash
|
|
# 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
|
|
- [Provider Setup](docs/reference/providers.md)
|
|
- [Example Tools](docs/reference/examples.md)
|
|
- [User Wiki](wiki/Home.md)
|
|
|
|
### Developer Documentation
|
|
- [Project Overview](docs/overview.md) - Start here to understand the codebase
|
|
- [Design Document](docs/reference/design.md)
|
|
- [Meta-Tools Design](docs/reference/meta-tools.md) - Tools that call other tools
|
|
- [Collections](docs/reference/collections.md) - Curated tool bundles
|
|
- [Registry API Design](docs/reference/registry-spec.md)
|
|
- [Web UI Design](docs/reference/web-ui-spec.md)
|