From 50ba841a62f2b7f600dd99cf6733c9f5d06cb9d3 Mon Sep 17 00:00:00 2001 From: rob Date: Sun, 18 Jan 2026 00:16:11 -0400 Subject: [PATCH] Update web UI documentation for current implementation - Replace API tokens with Connections/app pairing flow in Publishing section - Add moderation process documentation - Update Visual Builder section to describe PySide6 desktop GUI - Replace old TUI references (cmdforge ui, urwid, etc.) with desktop app - Update keyboard shortcuts for Qt application - Fix various outdated references throughout docs Co-Authored-By: Claude Opus 4.5 --- src/cmdforge/web/docs_content.py | 391 +++++++++++++++++++------------ 1 file changed, 245 insertions(+), 146 deletions(-) diff --git a/src/cmdforge/web/docs_content.py b/src/cmdforge/web/docs_content.py index 0f9fe08..150f4aa 100644 --- a/src/cmdforge/web/docs_content.py +++ b/src/cmdforge/web/docs_content.py @@ -28,7 +28,7 @@ Create tools that work with any AI provider and compose them like Unix pipes.

Two Ways to Build

-

cmdforge ui launches a visual builder with menus and forms. +

cmdforge launches the desktop application with a visual builder. cmdforge create uses a command-line wizard. Both create the same YAML config files.

@@ -76,7 +76,7 @@ output: "{summary}"

Next Steps

""", "headings": [ ("before-publishing", "Before Publishing"), ("create-account", "Create an Account"), - ("get-token", "Get an API Token"), + ("connect-account", "Connect Your Account"), ("publish", "Publish Your Tool"), + ("moderation", "Moderation Process"), ("versioning", "Versioning"), ("best-practices", "Best Practices"), ], @@ -2085,193 +2124,247 @@ output: "{formatted}" "visual-builder": { "title": "The Visual Builder", - "description": "Build tools without touching YAML using the terminal UI", + "description": "Build tools visually with the CmdForge desktop GUI", "content": """ -

Not everyone wants to write YAML by hand. CmdForge includes a full-featured -terminal UI that lets you create, edit, and test tools with menus and forms—no text editor required.

+

Not everyone wants to write YAML by hand. CmdForge includes a modern desktop +application that lets you create, edit, and manage tools with a visual interface—no text editor required.

What You'll Learn

    -
  • How to launch and navigate the visual builder
    • -
  • Creating tools with point-and-click menus
    • -
  • Managing providers without editing config files
    • +
  • How to launch and navigate the desktop application
    • +
  • Creating and editing tools with the visual builder
    • +
  • Browsing and installing tools from the registry
    • +
  • Managing AI providers
  • Testing tools before deploying them
-

Launching the Visual Builder

+

Launching the Application

-

Start the UI with a single command:

+

Start the desktop application with a single command:

-
cmdforge ui
+
cmdforge
-

You'll see a menu-driven interface that works in any terminal:

+

The application opens with a clean, modern interface featuring a sidebar for navigation and a main content area:

-
-
┌─────────────────────────────────────────────────────────┐
-│                  CmdForge Manager                      │
-├─────────────────────────────────────────────────────────┤
-│                                                          │
-│   [ List all tools      ]                               │
-│   [ Create new tool     ]                               │
-│   [ Edit existing tool  ]                               │
-│   [ Delete tool         ]                               │
-│   [ Test tool           ]                               │
-│   [ Manage providers    ]                               │
-│   [ Exit                ]                               │
-│                                                          │
-│         Use ↑↓ to navigate, Enter to select             │
-│                                                          │
-└─────────────────────────────────────────────────────────┘
+
+
+

Sidebar Navigation

+
    +
  • My Tools - View and manage your tools
    • +
  • Registry - Browse and install community tools
    • +
  • Providers - Configure AI backends
    • +
  • Profiles - Manage account connections
    • +
+
+
+

Features

+
    +
  • Light and dark themes
    • +
  • Keyboard shortcuts for power users
    • +
  • One-click registry connection
    • +
  • Real-time status syncing
    • +
+
-

Pro Tip: Mouse Support

-

If you have urwid installed (pip install urwid), - the UI supports mouse clicks! Just click on menu items instead of using arrow keys.

+

Pro Tip: Theme Switching

+

Use the View menu to switch between light and dark themes. + Your preference is saved automatically.

-

Creating Tools Visually

+

The My Tools Page

-

Select "Create new tool" to open the tool builder. It has two main sections:

+

The My Tools page shows all your installed tools organized by category in a tree view:

+ +
    +
  • Category grouping - Tools are organized under categories like Text Processing, Developer, Data, etc.
    • +
  • Tool details panel - Select a tool to see its description, arguments, and processing steps
    • +
  • Publish status - Icons indicate whether a tool is published, pending review, or local-only
    • +
+ +

From this page you can:

+ +
+
+

Create

+

New tool

+
+
+

Edit

+

Existing tool

+
+
+

Publish

+

To registry

+
+
+

Delete

+

Remove tool

+
+
+ +

Creating Tools with the Visual Builder

+ +

Click New Tool to open the tool builder. It has a form-based interface split into sections:

-

1. Info & Arguments

+

Basic Information

    -
  • Set tool name and description
    • -
  • Add custom flags (--format, --max, etc.)
    • -
  • Define the output template
    • +
  • Name - Unique identifier (lowercase, hyphens allowed)
    • +
  • Description - Brief summary for listings
    • +
  • Category - Select or create a category
-

2. Processing Steps

+

Arguments

    -
  • Add prompt steps (with provider selection)
    • -
  • Add code steps (Python processing)
    • -
  • Reorder steps with move up/down
    • +
  • Add custom flags (--format, --max, etc.)
    • +
  • Set default values and help text
    • +
  • Arguments become variables in your prompts
+
+

Processing Steps

+

Build your tool's logic by adding steps:

+
    +
  • Prompt Steps - Send input to an AI provider with a template
    • +
  • Code Steps - Process data with Python code
    • +
  • Reorder steps by dragging or using move buttons
    • +
  • Each step can pass its output to the next via variables
    • +
+
+

Step-by-Step: Creating a Summarizer

    -
  1. Launch: Run cmdforge ui
    2. -
  2. Select: Choose "Create new tool"
    3. -
  3. Info: Go to "Info & Args", set name to summarize
    4. -
  4. Add Argument: Click "Add Argument", set flag to --length, default to 100
    5. -
  5. Add Step: Go to "Steps", select "Add Prompt Step"
    6. -
  6. Provider: Choose your AI provider (or create one)
    7. -
  7. Prompt: Enter your prompt template with {input} and {length}
    8. -
  8. Save: Select "Save Tool" from the main menu
    9. +
  9. Launch: Run cmdforge to open the application
    10. +
  10. Navigate: Click My Tools in the sidebar
    11. +
  11. Create: Click the New Tool button
    12. +
  12. Basic Info: Enter name summarize and a description
    13. +
  13. Add Argument: Click Add Argument, set flag to --length with default 100
    14. +
  14. Add Step: Click Add Step and choose Prompt Step
    15. +
  15. Configure Step: Select your AI provider and enter the prompt template
    16. +
  16. Save: Click Save to create your tool
+

Browsing the Registry

+ +

The Registry page lets you discover and install tools created by the community:

+ +
    +
  • Search - Find tools by name or keyword
    • +
  • Filter by category - Browse Text Processing, Developer, Data tools, etc.
    • +
  • Sort - Order by downloads, newest, or alphabetically
    • +
  • Tool details - View description, author, version history, and download count
    • +
  • One-click install - Install any tool to your local machine
    • +
+ +
+

Version Selection

+

When installing a tool, you can choose a specific version or get the latest. + This is useful when you need a particular version for compatibility.

+
+

Managing Providers

-

The UI makes it easy to add, edit, and delete AI providers without touching config files:

- -
-
┌─────────────────────────────────────────────────────────┐
-│                   Manage Providers                       │
-├─────────────────────────────────────────────────────────┤
-│                                                          │
-│   claude         claude -p                              │
-│   opencode       opencode                                │
-│   mock           echo '[MOCK RESPONSE]'                 │
-│   ────────────────────────────────────────              │
-│   [ + Add New Provider ]                                │
-│   [ ← Back to Main Menu ]                               │
-│                                                          │
-└─────────────────────────────────────────────────────────┘
-
- -

Select a provider to edit or delete it. Adding a new provider shows a form:

- -
    -
  • Name: Short identifier (e.g., claude)
    • -
  • Command: The CLI command (e.g., claude -p)
    • -
  • Description: What this provider does
    • -
- -

Testing Tools

- -

Before deploying a tool, test it with the built-in mock provider:

- -
    -
  1. Select "Test tool" from the main menu
    2. -
  2. Choose the tool you want to test
    3. -
  3. Enter test input in the text editor
    4. -
  4. See the result (uses mock provider by default)
    5. -
- -

This lets you verify your prompts and variable substitution without making real API calls.

- -

Keyboard Shortcuts

+

The Providers page shows all configured AI backends in a table view:

- + + + + + + + + + + + + + + + + + + +
KeyColumnDescription
NameProvider identifier used in tool configs
CommandThe CLI command that's executed
DescriptionWhat this provider does
+ +

From this page you can:

+ +
    +
  • Add Provider - Create a new provider with name, command, and description
    • +
  • Edit - Modify an existing provider's configuration
    • +
  • Delete - Remove a provider you no longer need
    • +
  • Test - Send a test prompt to verify the provider works
    • +
+ +

Testing Tools

+ +

Test your tools before deploying them using the step-by-step test feature:

+ +
    +
  1. In the Tool Builder, click Test on any step
    2. +
  2. Enter sample input text
    3. +
  3. Set any argument values
    4. +
  4. Run the test to see the output
    5. +
+ +

This lets you verify prompts and variable substitution. For quick tests without API calls, configure a +mock provider that echoes input back.

+ +

Keyboard Shortcuts

+ +

Power users can navigate quickly with these shortcuts:

+ + + + + - - + + - - + + - + + + + + - - - - - +
Shortcut Action
↑ / ↓Navigate menu itemsCtrl+1 to Ctrl+4Switch to page (Tools, Registry, Providers, Profiles)
EnterSelect / confirmCtrl+NCreate new tool
EscCtrl+SSave current tool
Escape Cancel / go back
TabMove to next field (in forms)
qCtrl+Q Quit the application
-

UI Backends

- -

CmdForge automatically uses the best available terminal UI library:

- -
-
-

urwid (Best)

-

Mouse support, smooth

-

pip install urwid

-
-
-

snack

-

BIOS-style dialogs

-

apt install python3-newt

-
-
-

dialog/whiptail

-

Fallback option

-

apt install dialog

-
-
- -

CLI vs Visual Builder

+

CLI vs Visual Builder

When should you use each?

- - + + @@ -2281,37 +2374,43 @@ terminal UI that lets you create, edit, and test tools with menus and forms—no - + - + + + + + - - + +
Use the UI when...Use YAML when...Use the Visual Builder when...Use CLI/YAML when...
Building your first few toolsMaking quick editsMaking quick edits to configs
Managing providersBrowsing the registryScripting tool installation
Managing providers visually Copying tools between machines
Testing interactivelyVersion control integrationPublishing tools to the registryCI/CD integration

Next Up

-

Now that you know both ways to build tools:

+

Now that you know how to use the Visual Builder:

""", "headings": [ - ("launching", "Launching the Visual Builder"), - ("creating-tools", "Creating Tools Visually"), + ("launching", "Launching the Application"), + ("my-tools", "The My Tools Page"), + ("creating-tools", "Creating Tools with the Visual Builder"), + ("registry", "Browsing the Registry"), ("managing-providers", "Managing Providers"), ("testing", "Testing Tools"), ("keyboard-shortcuts", "Keyboard Shortcuts"), - ("ui-backends", "UI Backends"), - ("cli-vs-ui", "CLI vs Visual Builder"), + ("cli-vs-gui", "CLI vs Visual Builder"), ("next-up", "Next Up"), ], },