# CleverAgents v3.7.0 Terminal User Interface (TUI) Guide

## Overview

The CleverAgents v3.7.0 Terminal User Interface (TUI) provides a comprehensive, interactive environment for managing automations, sessions, skills, and resources directly from your terminal. This guide covers all aspects of the TUI, from basic navigation to advanced features.

## Table of Contents

1. [Getting Started](#getting-started)
2. [Main Interface](#main-interface)
3. [Navigation](#navigation)
4. [Automations Management](#automations-management)
5. [Sessions Management](#sessions-management)
6. [Skills Management](#skills-management)
7. [Resources Management](#resources-management)
8. [Settings and Configuration](#settings-and-configuration)
9. [Keyboard Shortcuts](#keyboard-shortcuts)
10. [Advanced Features](#advanced-features)
11. [Troubleshooting](#troubleshooting)

## Getting Started

### Installation

The TUI is included with CleverAgents v3.7.0. No additional installation is required.

### Launching the TUI

```bash
# Start the TUI
cleveragents tui

# Start with specific configuration
cleveragents tui --config=/path/to/config.yaml

# Start in debug mode
cleveragents tui --debug

# Start with specific theme
cleveragents tui --theme=dark
```

### System Requirements

- Terminal size: Minimum 80x24 characters
- Color support: 256-color or true color recommended
- Python 3.8+
- CleverAgents v3.7.0+

## Main Interface

### Layout Overview

The TUI is organized into several main sections:

```
┌─────────────────────────────────────────────────────────────────────┐
│ CleverAgents v3.7.0 - Main Dashboard                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  [1] Automations  [2] Sessions  [3] Skills  [4] Resources  [5] Set │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Active Automations (3)                                            │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │ ID        Name              Status      Progress   Duration  │ │
│  │ auto-001  data-pipeline     Running     ████░░░░░░ 2m 15s   │ │
│  │ auto-002  report-gen        Completed   ██████████ 5m 42s   │ │
│  │ auto-003  backup-task       Failed      ██████░░░░ 3m 28s   │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  System Status                                                      │
│  CPU: 45% | Memory: 2.1GB / 8GB | Connections: 8 | Uptime: 2d 3h │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│ Press 'h' for help | 'q' to quit | Arrow keys to navigate         │
└─────────────────────────────────────────────────────────────────────┘
```

### Color Scheme

- **Green**: Success, running, healthy
- **Yellow**: Warning, pending, in progress
- **Red**: Error, failed, critical
- **Blue**: Information, selected
- **Cyan**: Highlight, focus
- **White**: Normal text

## Navigation

### Menu Navigation

The TUI uses a tabbed interface for main sections:

```
[1] Automations  [2] Sessions  [3] Skills  [4] Resources  [5] Settings
```

### Navigating Between Tabs

```
- Press number key (1-5) to jump to tab
- Press Tab/Shift+Tab to move to next/previous tab
- Press Left/Right arrow keys to move between tabs
```

### List Navigation

Within each section, navigate lists using:

```
- Up/Down arrow keys: Move between items
- Page Up/Page Down: Scroll by page
- Home/End: Jump to first/last item
- Enter: Select/open item
- Space: Toggle selection (multi-select mode)
```

### Search and Filter

```
- Press '/' to open search
- Type search term
- Press Enter to search
- Press Escape to close search
- Press 'f' to open filter dialog
```

## Automations Management

### Viewing Automations

The Automations tab displays all automations with their current status.

```
Automations (12 total)
┌─────────────────────────────────────────────────────────────────────┐
│ ID        Name              Status      Progress   Duration   Error  │
├─────────────────────────────────────────────────────────────────────┤
│ auto-001  data-pipeline     Running     ████░░░░░░ 2m 15s    -      │
│ auto-002  report-gen        Completed   ██████████ 5m 42s    -      │
│ auto-003  backup-task       Failed      ██████░░░░ 3m 28s    Timeout│
│ auto-004  cleanup           Pending     ░░░░░░░░░░ -         -      │
│ auto-005  sync-data         Running     ██████░░░░ 1m 30s    -      │
└─────────────────────────────────────────────────────────────────────┘
```

### Creating New Automation

```
Press 'c' to create new automation

┌─ Create Automation ──────────────────────────────────────────────┐
│                                                                  │
│ Name: [_____________________________]                            │
│ Description: [_____________________________]                    │
│ Skills: [Select skills...]                                      │
│ Timeout (seconds): [300]                                        │
│ Retry Count: [3]                                                │
│ Retry Backoff: [2.0]                                            │
│                                                                  │
│ [Create]  [Cancel]                                              │
└──────────────────────────────────────────────────────────────────┘
```

### Viewing Automation Details

Press Enter on an automation to view details:

```
┌─ Automation Details: data-pipeline ──────────────────────────────┐
│                                                                  │
│ ID: auto-001                                                    │
│ Status: Running                                                 │
│ Created: 2024-01-15 10:30:45                                   │
│ Started: 2024-01-15 10:35:00                                   │
│ Duration: 2m 15s                                               │
│ Progress: 45%                                                  │
│                                                                  │
│ Skills:                                                         │
│   - data-extract (completed)                                   │
│   - data-validate (running)                                    │
│   - data-transform (pending)                                   │
│   - data-load (pending)                                        │
│                                                                  │
│ Metrics:                                                        │
│   CPU Usage: 45%                                               │
│   Memory: 512MB / 2GB                                          │
│   I/O Operations: 1,234                                        │
│                                                                  │
│ [View Logs]  [Cancel]  [Pause]  [Resume]  [Stop]              │
└──────────────────────────────────────────────────────────────────┘
```

### Executing Automations

```
Press 'e' to execute automation

┌─ Execute Automation ─────────────────────────────────────────────┐
│                                                                  │
│ Automation: data-pipeline                                       │
│                                                                  │
│ Context Variables:                                              │
│   project_id: [_____________________________]                   │
│   user_id: [_____________________________]                      │
│   environment: [production ▼]                                   │
│                                                                  │
│ Options:                                                        │
│   ☑ Enable logging                                              │
│   ☑ Enable metrics collection                                   │
│   ☐ Dry run                                                     │
│                                                                  │
│ [Execute]  [Cancel]                                             │
└──────────────────────────────────────────────────────────────────┘
```

### Viewing Logs

Press 'l' to view automation logs:

```
┌─ Logs: data-pipeline ────────────────────────────────────────────┐
│                                                                  │
│ [2024-01-15 10:35:00] INFO: Starting automation                │
│ [2024-01-15 10:35:01] INFO: Loading context                    │
│ [2024-01-15 10:35:02] INFO: Executing skill: data-extract      │
│ [2024-01-15 10:35:15] INFO: Skill completed: data-extract      │
│ [2024-01-15 10:35:16] INFO: Executing skill: data-validate     │
│ [2024-01-15 10:35:45] WARN: Validation found 5 issues          │
│ [2024-01-15 10:35:46] INFO: Executing skill: data-transform    │
│ [2024-01-15 10:36:00] INFO: Running...                         │
│                                                                  │
│ [Scroll: ↑↓] [Filter: f] [Export: e] [Close: q]                │
└──────────────────────────────────────────────────────────────────┘
```

## Sessions Management

### Viewing Sessions

The Sessions tab displays all recorded sessions.

```
Sessions (8 total)
┌─────────────────────────────────────────────────────────────────────┐
│ ID          Automation        Status      Created              Dur   │
├─────────────────────────────────────────────────────────────────────┤
│ sess-001    data-pipeline     Completed   2024-01-15 10:30:45  5m 42s│
│ sess-002    report-gen        Completed   2024-01-15 09:15:20  3m 15s│
│ sess-003    backup-task       Failed      2024-01-15 08:00:00  2m 30s│
│ sess-004    sync-data         Completed   2024-01-14 23:45:30  1m 10s│
└─────────────────────────────────────────────────────────────────────┘
```

### Session Details

Press Enter on a session to view details:

```
┌─ Session Details: sess-001 ──────────────────────────────────────┐
│                                                                  │
│ ID: sess-001                                                    │
│ Automation: data-pipeline                                       │
│ Status: Completed                                               │
│ Created: 2024-01-15 10:30:45                                   │
│ Started: 2024-01-15 10:35:00                                   │
│ Completed: 2024-01-15 10:40:42                                 │
│ Duration: 5m 42s                                               │
│                                                                  │
│ Execution Timeline:                                             │
│   data-extract:    ████████████░░░░░░░░ 2m 15s                │
│   data-validate:   ████████░░░░░░░░░░░░ 1m 30s                │
│   data-transform:  ██████████░░░░░░░░░░ 1m 45s                │
│   data-load:       ████████░░░░░░░░░░░░ 1m 12s                │
│                                                                  │
│ [View Timeline]  [Export]  [Delete]  [Close]                   │
└──────────────────────────────────────────────────────────────────┘
```

### Exporting Sessions

Press 'e' to export session:

```
┌─ Export Session ─────────────────────────────────────────────────┐
│                                                                  │
│ Session: sess-001                                               │
│ Format: [JSON ▼]                                                │
│ Include:                                                        │
│   ☑ Logs                                                        │
│   ☑ Metrics                                                     │
│   ☑ Timeline                                                    │
│   ☑ Context                                                     │
│                                                                  │
│ Output File: [session-001-export.json]                          │
│                                                                  │
│ [Export]  [Cancel]                                              │
└──────────────────────────────────────────────────────────────────┘
```

## Skills Management

### Viewing Skills

The Skills tab displays all available skills.

```
Skills (24 total)
┌─────────────────────────────────────────────────────────────────────┐
│ Name              Category      Status      Version   Last Updated   │
├─────────────────────────────────────────────────────────────────────┤
│ data-extract      Data          Active      2.1.0     2024-01-10    │
│ data-validate     Data          Active      1.5.0     2024-01-08    │
│ data-transform    Data          Active      3.0.0     2024-01-15    │
│ data-load         Data          Active      2.0.0     2024-01-12    │
│ report-generate   Reporting     Active      1.2.0     2024-01-05    │
└─────────────────────────────────────────────────────────────────────┘
```

### Skill Details

Press Enter on a skill to view details:

```
┌─ Skill Details: data-extract ────────────────────────────────────┐
│                                                                  │
│ Name: data-extract                                              │
│ Version: 2.1.0                                                  │
│ Category: Data                                                  │
│ Status: Active                                                  │
│ Description: Extract data from various sources                  │
│                                                                  │
│ Parameters:                                                     │
│   source (required): Data source URL                            │
│   format (optional): Output format (json, csv, xml)             │
│   timeout (optional): Timeout in seconds (default: 300)         │
│                                                                  │
│ Returns:                                                        │
│   data: Extracted data                                          │
│   count: Number of records                                      │
│   duration: Execution time                                      │
│                                                                  │
│ [View Documentation]  [Test]  [Edit]  [Close]                  │
└──────────────────────────────────────────────────────────────────┘
```

### Testing Skills

Press 't' to test a skill:

```
┌─ Test Skill: data-extract ───────────────────────────────────────┐
│                                                                  │
│ Parameters:                                                     │
│   source: [_____________________________]                       │
│   format: [json ▼]                                              │
│   timeout: [300]                                                │
│                                                                  │
│ [Run Test]  [Cancel]                                            │
│                                                                  │
│ Test Results:                                                   │
│ Status: Success                                                 │
│ Duration: 1.23s                                                │
│ Output:                                                         │
│   data: [{"id": 1, "name": "Item 1"}, ...]                     │
│   count: 1000                                                   │
│   duration: 1.23                                                │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

## Resources Management

### Viewing Resources

The Resources tab displays all available resources.

```
Resources (15 total)
┌─────────────────────────────────────────────────────────────────────┐
│ Name              Type          Status      Created              Exp │
├─────────────────────────────────────────────────────────────────────┤
│ prod-database     Database      Active      2024-01-01           -   │
│ api-key-prod      Credential    Active      2024-01-01           -   │
│ s3-bucket         Storage       Active      2024-01-05           -   │
│ smtp-config       Service       Active      2024-01-10           -   │
└─────────────────────────────────────────────────────────────────────┘
```

### Resource Details

Press Enter on a resource to view details:

```
┌─ Resource Details: prod-database ────────────────────────────────┐
│                                                                  │
│ Name: prod-database                                             │
│ Type: Database                                                  │
│ Status: Active                                                  │
│ Created: 2024-01-01 00:00:00                                   │
│ Last Used: 2024-01-15 10:40:42                                 │
│                                                                  │
│ Configuration:                                                  │
│   Host: db.example.com                                          │
│   Port: 5432                                                    │
│   Database: production                                          │
│   Connection Pool: 10                                           │
│                                                                  │
│ Usage Statistics:                                               │
│   Total Connections: 1,234                                      │
│   Active Connections: 5                                         │
│   Failed Connections: 2                                         │
│                                                                  │
│ [View Logs]  [Test Connection]  [Edit]  [Close]                │
└──────────────────────────────────────────────────────────────────┘
```

## Settings and Configuration

### Accessing Settings

Press '5' to go to Settings tab or press 's' from any tab.

```
Settings
┌─────────────────────────────────────────────────────────────────────┐
│ [1] General      [2] Appearance  [3] Logging  [4] Advanced          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│ General Settings                                                    │
│                                                                     │
│ API URL: [http://localhost:8000]                                   │
│ API Key: [sk-****...****]                                          │
│ Default Timeout: [300] seconds                                     │
│ Auto-refresh: [☑] Every [5] seconds                                │
│ Confirm on Delete: [☑]                                             │
│                                                                     │
│ [Save]  [Reset]  [Cancel]                                          │
└─────────────────────────────────────────────────────────────────────┘
```

### Appearance Settings

```
Appearance Settings

Theme: [Dark ▼]
Color Scheme: [Default ▼]
Font Size: [Medium ▼]
Show Status Bar: [☑]
Show Line Numbers: [☑]
Syntax Highlighting: [☑]

[Save]  [Reset]  [Cancel]
```

### Logging Settings

```
Logging Settings

Log Level: [INFO ▼]
Log Format: [JSON ▼]
Log Output: [Console ▼]
Max Log Size: [100] MB
Log Retention: [30] days
Enable Audit Logging: [☑]

[Save]  [Reset]  [Cancel]
```

## Keyboard Shortcuts

### Global Shortcuts

| Key | Action |
|-----|--------|
| `1-5` | Jump to tab (Automations, Sessions, Skills, Resources, Settings) |
| `Tab` / `Shift+Tab` | Move to next/previous tab |
| `h` | Show help |
| `q` | Quit TUI |
| `?` | Show keyboard shortcuts |
| `Ctrl+C` | Force quit |

### Navigation Shortcuts

| Key | Action |
|-----|--------|
| `↑` / `↓` | Move up/down in list |
| `←` / `→` | Move left/right between tabs |
| `Page Up` / `Page Down` | Scroll by page |
| `Home` / `End` | Jump to first/last item |
| `Enter` | Select/open item |
| `Space` | Toggle selection (multi-select) |

### List Shortcuts

| Key | Action |
|-----|--------|
| `/` | Open search |
| `f` | Open filter |
| `c` | Create new item |
| `e` | Edit selected item |
| `d` | Delete selected item |
| `r` | Refresh list |
| `Ctrl+A` | Select all |
| `Ctrl+D` | Deselect all |

### Automation Shortcuts

| Key | Action |
|-----|--------|
| `e` | Execute automation |
| `l` | View logs |
| `m` | View metrics |
| `p` | Pause automation |
| `Shift+P` | Resume automation |
| `s` | Stop automation |
| `c` | Cancel automation |

### Session Shortcuts

| Key | Action |
|-----|--------|
| `e` | Export session |
| `i` | Import session |
| `v` | View timeline |
| `l` | View logs |
| `m` | View metrics |

## Advanced Features

### Real-time Monitoring

The TUI provides real-time monitoring of automations with live updates.

```
Real-time Monitoring Dashboard

┌─ Execution Timeline ─────────────────────────────────────────────┐
│                                                                  │
│ data-extract:    ████████████░░░░░░░░ 2m 15s (45%)             │
│ data-validate:   ████████░░░░░░░░░░░░ 1m 30s (30%)             │
│ data-transform:  ██████████░░░░░░░░░░ 1m 45s (35%)             │
│ data-load:       ░░░░░░░░░░░░░░░░░░░░ 0s (0%)                 │
│                                                                  │
│ Total Progress: ███████░░░░░░░░░░░░░░ 35%                      │
│ Estimated Time Remaining: 6m 45s                                │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

┌─ Resource Usage ─────────────────────────────────────────────────┐
│                                                                  │
│ CPU:    ████████░░░░░░░░░░░░ 40%                               │
│ Memory: ██████░░░░░░░░░░░░░░ 30%                               │
│ Disk:   ███░░░░░░░░░░░░░░░░░ 15%                               │
│ Network: ██████████░░░░░░░░░░ 50%                              │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

### Bulk Operations

Select multiple items and perform bulk operations:

```
# Select multiple automations
Press Space on each automation to select

# Perform bulk operation
Press 'e' to execute all selected
Press 'd' to delete all selected
Press 's' to stop all selected
```

### Custom Dashboards

Create custom dashboards for monitoring:

```
Press 'd' to create custom dashboard

┌─ Create Dashboard ───────────────────────────────────────────────┐
│                                                                  │
│ Name: [_____________________________]                            │
│                                                                  │
│ Widgets:                                                        │
│   ☑ Execution Timeline                                          │
│   ☑ Resource Usage                                              │
│   ☑ Error Log                                                   │
│   ☑ Performance Metrics                                         │
│   ☐ Custom Metrics                                              │
│                                                                  │
│ Refresh Interval: [5] seconds                                   │
│                                                                  │
│ [Create]  [Cancel]                                              │
└──────────────────────────────────────────────────────────────────┘
```

## Troubleshooting

### TUI Not Starting

**Problem**: TUI fails to start
**Solution**:
```bash
# Check terminal size
echo $LINES x $COLUMNS

# Try with debug mode
cleveragents tui --debug

# Check logs
tail -f ~/.cleveragents/logs/tui.log
```

### Slow Performance

**Problem**: TUI is slow or unresponsive
**Solution**:
- Reduce auto-refresh interval in settings
- Close unnecessary tabs
- Check system resources
- Restart TUI

### Display Issues

**Problem**: Colors or text are not displaying correctly
**Solution**:
- Check terminal color support: `echo $TERM`
- Try different theme: `cleveragents tui --theme=light`
- Update terminal emulator
- Check terminal encoding: `echo $LANG`

### Connection Issues

**Problem**: Cannot connect to API
**Solution**:
- Check API URL in settings
- Verify API key is valid
- Check network connectivity
- Review API logs

## Additional Resources

- [CleverAgents API Reference](../api/v1.md)
- [Automation Guide](../reference/automations.md)
- [Skills Development Guide](../reference/skill-development.md)
- [Troubleshooting Guide](../reference/troubleshooting.md)

---

**Last Updated**: April 2024
**Version**: 3.7.0
