From 01995392dab8321390a402ac75a01cdc9e4a8d87 Mon Sep 17 00:00:00 2001 From: rob Date: Thu, 1 Jan 2026 06:36:34 -0400 Subject: [PATCH] Add Visual Builder tutorial for the TUI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - New comprehensive tutorial covering smarttools ui - ASCII art mockups of menu interface - Documents all keyboard shortcuts - Explains UI backends (urwid, snack, dialog) - Comparison table: CLI vs Visual Builder use cases - Updated getting-started to mention both UI and CLI options - Added visual-builder to documentation TOC πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- src/smarttools/web/docs_content.py | 248 ++++++++++++++++++++++++++++- 1 file changed, 245 insertions(+), 3 deletions(-) diff --git a/src/smarttools/web/docs_content.py b/src/smarttools/web/docs_content.py index f5c2e00..e6abb4e 100644 --- a/src/smarttools/web/docs_content.py +++ b/src/smarttools/web/docs_content.py @@ -27,8 +27,9 @@ Create tools that work with any AI provider and compose them like Unix pipes.

# Install SmartTools pip install smarttools -# Create your first tool interactively -smarttools create +# Create your first tool (choose your style) +smarttools ui # Visual builder with menus +smarttools create # CLI wizard # Or install a tool from the registry smarttools registry install official/summarize @@ -36,6 +37,12 @@ smarttools registry install official/summarize # Use it! cat article.txt | summarize +
+

Two Ways to Build

+

smarttools ui launches a visual builder with menus and forms. + smarttools create uses a command-line wizard. Both create the same YAML config files.

+
+

How It Works

Each tool is a YAML file that defines:

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

    Next Steps

    @@ -2065,6 +2073,239 @@ output: "{formatted}" ("whats-next", "What's Next?"), ], }, + + "visual-builder": { + "title": "The Visual Builder", + "description": "Build tools without touching YAML using the terminal UI", + "content": """ +

    Not everyone wants to write YAML by hand. SmartTools includes a full-featured +terminal UI that lets you create, edit, and test tools with menus and formsβ€”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
      • +
    • Testing tools before deploying them
      • +
    +
    + +

    Launching the Visual Builder

    + +

    Start the UI with a single command:

    + +
    smarttools ui
    + +

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

    + +
    +
    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚                  SmartTools Manager                      β”‚
+β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+β”‚                                                          β”‚
+β”‚   [ List all tools      ]                               β”‚
+β”‚   [ Create new tool     ]                               β”‚
+β”‚   [ Edit existing tool  ]                               β”‚
+β”‚   [ Delete tool         ]                               β”‚
+β”‚   [ Test tool           ]                               β”‚
+β”‚   [ Manage providers    ]                               β”‚
+β”‚   [ Exit                ]                               β”‚
+β”‚                                                          β”‚
+β”‚         Use ↑↓ to navigate, Enter to select             β”‚
+β”‚                                                          β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
    +
    + +
    +

    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.

    +
    + +

    Creating Tools Visually

    + +

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

    + +
    +
    +

    1. Info & Arguments

    +
      +
    • Set tool name and description
      • +
    • Add custom flags (--format, --max, etc.)
      • +
    • Define the output template
      • +
    +
    +
    +

    2. Processing Steps

    +
      +
    • Add prompt steps (with provider selection)
      • +
    • Add code steps (Python processing)
      • +
    • Reorder steps with move up/down
      • +
    +
    +
    + +

    Step-by-Step: Creating a Summarizer

    + +
      +
    1. Launch: Run smarttools 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. +
    + +

    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

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    KeyAction
    ↑ / ↓Navigate menu items
    EnterSelect / confirm
    EscCancel / go back
    TabMove to next field (in forms)
    qQuit the application
    + +

    UI Backends

    + +

    SmartTools 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

    + +

    When should you use each?

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Use the UI when...Use YAML when...
    You're new to SmartToolsYou're comfortable with YAML
    Building your first few toolsMaking quick edits
    Managing providersCopying tools between machines
    Testing interactivelyVersion control integration
    + +

    Next Up

    + +

    Now that you know both ways to build tools:

    + + +""", + "headings": [ + ("launching", "Launching the Visual Builder"), + ("creating-tools", "Creating Tools Visually"), + ("managing-providers", "Managing Providers"), + ("testing", "Testing Tools"), + ("keyboard-shortcuts", "Keyboard Shortcuts"), + ("ui-backends", "UI Backends"), + ("cli-vs-ui", "CLI vs Visual Builder"), + ("next-up", "Next Up"), + ], + }, } @@ -2082,6 +2323,7 @@ def get_toc(): SimpleNamespace(slug="getting-started", title="Getting Started", children=[ SimpleNamespace(slug="installation", title="Installation"), SimpleNamespace(slug="first-tool", title="Your First Tool"), + SimpleNamespace(slug="visual-builder", title="Visual Builder"), SimpleNamespace(slug="yaml-config", title="YAML Config"), ]), SimpleNamespace(slug="arguments", title="Custom Arguments", children=[]),