CmdForge/olddocs/PROJECT.md

CmdForge Project Overview

Document Status (January 2026): This overview is mostly accurate but the source structure section is outdated. The TUI has been replaced by a PySide6 GUI. Database now has 25+ tables. For current architecture, see src/cmdforge/ directly.

This document provides a comprehensive overview of the CmdForge project structure, components, and how everything fits together.

What is CmdForge?

CmdForge is a personal tool builder for AI-powered CLI commands. It consists of three main components:

1. CLI Tool (cmdforge) - Create, manage, and run AI-powered command-line tools
2. Registry API - REST API for publishing and discovering tools
3. Web UI - Browser interface for the registry with docs, search, and user dashboard

Quick Reference

Component	Location	Purpose
CLI	src/cmdforge/cli.py	Main entry point for cmdforge command
Registry API	src/cmdforge/registry/	REST API for tool registry
Web UI	src/cmdforge/web/	Flask web application
Tool Storage	~/.cmdforge/	User's installed tools
Database	data/cmdforge.db	SQLite with FTS5 search

Architecture Diagrams

See docs/diagrams/ for visual representations:

• system-architecture.svg - How components interact
• deployment-architecture.svg - Production deployment setup
• source-organization.svg - Code structure

Source Code Structure

src/cmdforge/
├── cli/                # CLI commands
│   ├── __init__.py     # Entry point, subcommand routing
│   └── registry_commands.py  # Registry CLI commands
├── tool.py             # Tool dataclasses, YAML loading
├── runner.py           # Step execution engine
├── providers.py        # AI provider abstraction
├── profiles.py         # AI persona profiles
├── config.py           # Global configuration
│
├── gui/                # PySide6 Desktop GUI (primary UI)
│   ├── main_window.py  # Main application window
│   ├── pages/          # Tools, Registry, Providers, Profiles pages
│   ├── dialogs/        # Step editors, Publish, Connect dialogs
│   └── workers/        # Background threads for API calls
│
├── registry/           # Registry API Server
│   ├── app.py          # Flask API with 100+ endpoints
│   ├── db.py           # Database operations, FTS5 search (25+ tables)
│   ├── rate_limit.py   # API rate limiting
│   ├── scrutiny.py     # Automated code analysis
│   ├── similarity.py   # Duplicate detection
│   └── sync.py         # Git sync for tool submissions
│
├── web/                # Web UI Application
│   ├── app.py          # Flask web app
│   ├── routes.py       # Page routes and handlers
│   ├── auth.py         # Password hashing, login/register
│   ├── sessions.py     # Session management
│   ├── forum/          # Forum blueprint
│   ├── templates/      # Jinja HTML templates
│   └── static/         # CSS (Tailwind), JS, images
│
└── registry_client.py  # CLI client for registry API

Database Schema

SQLite database at ~/.cmdforge/registry.db (or via CMDFORGE_REGISTRY_DB env var):

Table	Purpose
publishers	User accounts with roles, banning, verification
tools	Published tools with moderation status, fork tracking
api_tokens	Authentication tokens for API access
download_stats	Tool download tracking by date
reviews	Tool reviews with 1-5 star ratings
review_votes	Helpful/unhelpful votes on reviews
tool_issues	Bug, security, compatibility issue reports
collections	Curated tool groups
announcements	Admin announcements
featured_tools	Featured tool placement
featured_contributors	Featured publisher placement
reports	Abuse reports for moderation
audit_log	Admin action audit trail
pairing_requests	App pairing flow
web_sessions	Session storage
consents	User consent for analytics/ads
pageviews	Analytics tracking
tools_fts	Full-text search index (FTS5)
tool_stats	Cached tool statistics
publisher_stats	Cached publisher statistics
registry_settings	Runtime-configurable settings

API Endpoints

Base URL: /api/v1/

Endpoint	Method	Purpose
/tools	GET	List/search tools
/tools/<owner>/<name>	GET	Get tool details
/tools/<owner>/<name>	POST	Publish tool (auth required)
/tools/<owner>/<name>/download	POST	Record download
/me	GET	Current user info
/tokens	GET/POST	Manage API tokens

Web Routes

Route	Purpose
/	Homepage with featured tools
/tools	Tool browser with search
/tools/<owner>/<name>	Tool detail page
/docs/*	Documentation pages
/login, /register	Authentication
/dashboard/*	User dashboard, token management

Key Files to Know

Configuration

• ~/.cmdforge/providers.yaml - AI provider configurations
• ~/.cmdforge/config.yaml - Global settings
• ~/.cmdforge/<tool>/config.yaml - Individual tool configs

Development

• pyproject.toml - Package configuration
• pytest.ini - Test configuration
• tailwind.config.js - Tailwind CSS configuration

Documentation

• docs/REGISTRY.md - Registry design document (comprehensive)
• docs/WEB_UI.md - Web UI design document (comprehensive)
• wiki/Home.md - User-facing wiki documentation
• CLAUDE.md - Development guidance for AI assistants

Running the Project

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run CLI
python -m cmdforge.cli

# Run web server (development)
cd src/cmdforge/web
flask run --port 5050

Production

# Using gunicorn
gunicorn -w 4 -b 0.0.0.0:5050 'cmdforge.web.app:create_app()'

# Environment variables needed:
# FLASK_ENV=production
# SECRET_KEY=<your-secret-key>
# SENTRY_DSN=<optional-sentry-dsn>
# SITE_URL=https://your-domain.com

systemd Service

See docs/DEPLOYMENT.md for systemd service configuration.

Testing

# Run all tests
pytest

# Run specific test
pytest tests/test_name.py::test_function

# Run with coverage
pytest --cov=cmdforge

Design Documents

For detailed design decisions and specifications:

• docs/REGISTRY.md - Complete registry API design (Phases 1-8)
• docs/WEB_UI.md - Complete web UI design (Phase 7)
• wiki/Home.md - User documentation for CLI usage

Archive

Old development discussions and diagrams are preserved in archive/discussions/ for historical reference.