"""Help dialogs for CmdForge GUI."""
from PySide6.QtWidgets import (
QDialog, QVBoxLayout, QHBoxLayout, QLabel, QPushButton,
QTextBrowser
)
from PySide6.QtCore import Qt
# Help content for quick guides
HELP_CONTENT = {
"getting_started": {
"title": "Getting Started with CmdForge",
"content": """
Welcome to CmdForge!
CmdForge lets you create AI-powered command-line tools that work like any Unix command.
Quick Start Steps:
- Configure a Provider - Go to Providers in the sidebar and add an AI backend (like Claude or GPT). This is required before running AI tools.
- Browse the Registry - Check out the Registry to discover tools shared by the community.
- Install Tools - Click on any tool and hit Install to add it to your system.
- Create Your Own - Use the Tool Builder to create custom AI-powered commands.
- Use in Terminal - Run your tools like any command:
my-tool < input.txt
Key Concepts:
- Steps - Tools are made of steps: Prompt (AI call), Code (Python), or Tool (chain another tool)
- Variables - Use
{variable} to pass data between steps
- Arguments - Add flags like
--format that users can set when running the tool
Keyboard Shortcuts:
Ctrl+N | Create new tool |
Ctrl+S | Save current tool |
Ctrl+R | Refresh current page |
Ctrl+1-4 | Navigate to pages |
Ctrl+Q | Quit |
Escape | Close tool builder |
"""
},
"create_tool": {
"title": "How to Create a Tool",
"content": """
Creating a New Tool
Step 1: Start the Tool Builder
Click Create Tool on the Welcome page, or press Ctrl+N from anywhere.
Step 2: Fill in Basic Info
- Name - Use lowercase letters, numbers, and hyphens (e.g.,
summarize-text)
- Description - Brief explanation shown in listings
- Category - Pick from Text, Developer, Data, or add your own
Step 3: Add Arguments (Optional)
Arguments let users customize tool behavior:
- Flag - The command-line flag (e.g.,
--max)
- Variable - Name to use in templates (e.g.,
max)
- Default - Value when flag isn't provided
Step 4: Add Steps
Steps define what your tool does:
- Prompt Step - Calls an AI provider with your template. Use
{input} for stdin content.
- Code Step - Runs Python code. Variables are available directly (e.g.,
input, response).
- Tool Step - Calls another CmdForge tool, enabling composition.
Step 5: Set Output Template
The output template defines what your tool prints. Use {variable} to include step outputs.
Example: {response} prints the last AI response.
Step 6: Save
Press Ctrl+S or click Save. Your tool is now available as a command!
Example: Simple Summarizer
Name: summarize
Steps:
1. Prompt [claude] -> response
"Summarize this text: {input}"
Output: {response}
Run it: echo "Long text..." | summarize
"""
},
"install_tools": {
"title": "How to Install Tools",
"content": """
Installing Tools from the Registry
Step 1: Open the Registry
Click Registry in the sidebar to browse community tools.
Step 2: Find a Tool
- Search - Type keywords in the search box
- Filter by Category - Use the dropdown to narrow results
- Sort - Order by popularity, newest, or name
- Tags - Click tags on tools to filter by tag
Step 3: Review Tool Details
Click on a tool to see:
- Description and usage information
- Rating and download count
- Publisher reputation
- Available versions
Step 4: Install
- Select a version (or use Latest)
- Click Install
- Wait for confirmation
Step 5: Use the Tool
Installed tools are available immediately in your terminal:
echo "text" | tool-name
cat file.txt | tool-name --flag value
tool-name --help
Updates
Tools with available updates show a green arrow (↑) in the list. Click Update to get the latest version.
Managing Installed Tools
Go to Tools in the sidebar to see all your installed tools, edit them, or delete ones you no longer need.
"""
},
"publish_tools": {
"title": "How to Publish Tools",
"content": """
Publishing Your Tools
Prerequisites
- A tool you've created and tested
- A registry account (sign up at cmdforge.brrd.tech)
Step 1: Connect Your Account
- Go to the Providers page
- Click Connect to Registry
- Log in or register
Step 2: Prepare Your Tool
- Give it a clear, descriptive name
- Write a helpful description
- Choose the right category
- Test it thoroughly
Step 3: Publish
- Go to the Tools page
- Select the tool you want to publish
- Click Publish
- Add tags to help users find it
- Set the initial version number
- Click Submit
Versioning
When you update a published tool:
- Patch (1.0.0 → 1.0.1) - Bug fixes
- Minor (1.0.0 → 1.1.0) - New features, backward compatible
- Major (1.0.0 → 2.0.0) - Breaking changes
Best Practices
- Write clear descriptions and examples
- Use semantic versioning
- Test before publishing updates
- Respond to user feedback
"""
},
"keyboard_shortcuts": {
"title": "Keyboard Shortcuts",
"content": """
Keyboard Shortcuts
Global
Ctrl+N | Create new tool |
Ctrl+S | Save current tool |
Ctrl+R | Refresh current page |
Ctrl+Q | Quit application |
F1 | Show help |
Navigation
Ctrl+1 | Go to Welcome page |
Ctrl+2 | Go to Tools page |
Ctrl+3 | Go to Registry page |
Ctrl+4 | Go to Providers page |
Tool Builder
Escape | Close builder / cancel |
Ctrl+S | Save tool |
Lists and Tables
Double-click | Edit selected item |
Drag & Drop | Reorder steps |
"""
}
}
class QuickGuideDialog(QDialog):
"""Dialog showing a quick guide on a topic."""
def __init__(self, guide_key: str, parent=None):
super().__init__(parent)
guide = HELP_CONTENT.get(guide_key, {})
self.setWindowTitle(guide.get("title", "Help"))
self.setMinimumSize(550, 450)
self.resize(600, 500)
self.setModal(True)
self._setup_ui(guide)
def _setup_ui(self, guide: dict):
"""Set up the dialog UI."""
layout = QVBoxLayout(self)
layout.setContentsMargins(24, 24, 24, 24)
layout.setSpacing(16)
# Content browser with styled HTML
browser = QTextBrowser()
browser.setOpenExternalLinks(True)
browser.setStyleSheet("""
QTextBrowser {
border: none;
background-color: transparent;
font-size: 13px;
}
""")
# Build styled content
content = f"""
{guide.get("content", "")}
"""
browser.setHtml(content)
layout.addWidget(browser, 1)
# Close button
btn_layout = QHBoxLayout()
btn_layout.addStretch()
btn_close = QPushButton("Close")
btn_close.setMinimumWidth(100)
btn_close.clicked.connect(self.accept)
btn_layout.addWidget(btn_close)
layout.addLayout(btn_layout)
class AboutDialog(QDialog):
"""About CmdForge dialog."""
def __init__(self, parent=None):
super().__init__(parent)
self.setWindowTitle("About CmdForge")
self.setFixedSize(400, 300)
self.setModal(True)
self._setup_ui()
def _setup_ui(self):
"""Set up the dialog UI."""
layout = QVBoxLayout(self)
layout.setContentsMargins(32, 32, 32, 32)
layout.setSpacing(16)
# Logo/title
title = QLabel("CmdForge")
title.setStyleSheet("""
font-size: 32px;
font-weight: bold;
color: #667eea;
""")
title.setAlignment(Qt.AlignCenter)
layout.addWidget(title)
# Tagline
tagline = QLabel("AI-Powered CLI Tool Builder")
tagline.setStyleSheet("font-size: 14px; color: #718096;")
tagline.setAlignment(Qt.AlignCenter)
layout.addWidget(tagline)
layout.addSpacing(16)
# Version info
try:
from cmdforge import __version__
version = __version__
except ImportError:
version = "unknown"
version_label = QLabel(f"Version {version}")
version_label.setStyleSheet("color: #4a5568;")
version_label.setAlignment(Qt.AlignCenter)
layout.addWidget(version_label)
# Description
desc = QLabel(
"Create custom terminal commands that call AI providers,\n"
"chain prompts with Python code, and use them like\n"
"any Unix pipe command."
)
desc.setStyleSheet("color: #718096; font-size: 12px;")
desc.setAlignment(Qt.AlignCenter)
layout.addWidget(desc)
layout.addStretch()
# Links
links = QLabel(
'Website'
)
links.setOpenExternalLinks(True)
links.setAlignment(Qt.AlignCenter)
layout.addWidget(links)
# Close button
btn_close = QPushButton("Close")
btn_close.clicked.connect(self.accept)
layout.addWidget(btn_close)