🖥️ Text User Interface (TUI)

Your bot’s control center, right in the terminal! 🎮

💡 What's a TUI? It's like a GUI, but in your terminal! Think mouse support, menus, and real-time updates—all without leaving the command line.

✨ Features at a Glance

📊 Status Monitoring

Real-time bot status, connections, and metrics

🏠 Room Management

View, join, leave, and message rooms

🔐 Device Verification

Emoji, QR code, and fingerprint verification

📝 Log Viewing

Real-time log streaming in the terminal

🖱️ Mouse Support

Click buttons and navigate menus

🎨 Pretty Colors

ChatrixCD brand green (#3e836b) 💚

🚀 Launching the TUI

The TUI launches automatically when you run ChatrixCD in an interactive terminal:

# Start with TUI (default)
chatrixcd

# Run without TUI (log-only mode)
chatrixcd -L

# Enable colored output
chatrixcd -C

TUI Interface

The main menu provides quick access to all bot functions:

┌─────────────────────────────────────────────────────────────┐
│ ChatrixCD                                                   │
└─────────────────────────────────────────────────────────────┘

                        ChatrixCD
            Matrix CI/CD Bot - Interactive Interface

  ┌─────────────────────────────────────────────────────────┐
  │ STATUS - Show bot status                                │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ ADMINS - View admin users                               │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ ROOMS - Show joined rooms                               │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ SESSIONS - Session management                           │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ ALIASES - Manage command aliases                        │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ SAY - Send message to room                              │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ LOG - View log                                          │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ SET - Change operational variables                      │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ SHOW - Show current configuration                       │
  └─────────────────────────────────────────────────────────┘
  
  ┌─────────────────────────────────────────────────────────┐
  │ QUIT - Exit                                             │
  └─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ q Quit                                                      │
└─────────────────────────────────────────────────────────────┘

STATUS

Displays real-time bot status information:

  • Matrix Connection: Connected/Disconnected status
  • Semaphore Connection: Connection status to Semaphore UI
  • Uptime: How long the bot has been running
  • Messages Processed: Total number of messages processed
  • Errors: Count of errors encountered
  • Warnings: Count of warnings logged
┌─────────────────────────────────────────────────────────────┐
│ ChatrixCD                                                   │
└─────────────────────────────────────────────────────────────┘

Bot Status

Matrix: Connected
Semaphore: Connected
Uptime: 2h 34m 12s

Metrics
Messages Processed: 147
Errors: 0
Warnings: 2

┌─────────────────────────────────────────────────────────────┐
│ escape Back                                                 │
└─────────────────────────────────────────────────────────────┘

ADMINS

Lists all configured admin users:

Admin Users

  • @admin1:matrix.org
  • @admin2:example.com
  • @cicd-admin:company.org

ROOMS

Shows all rooms the bot has joined:

Rooms

  • DevOps Team (!abcd1234:matrix.org)
  • CI/CD Notifications (!efgh5678:example.com)
  • Production Deploys (!ijkl9012:company.org)

SESSIONS

Provides session management options:

  • View Olm encryption sessions
  • Reset Olm sessions (future feature)
  • Verify sessions with other devices (future feature)

ALIASES

Manage command aliases to create custom shortcuts for frequently used commands.

Features:

  • View all configured aliases
  • Add new aliases with custom names (emoji supported!)
  • Delete existing aliases
  • Validate commands before creating aliases

Adding an Alias:

  1. Press a or click “Add Alias”
  2. Enter the alias name (e.g., “deploy”, “🚀”, “deploy😱”)
  3. Enter the command to alias to (e.g., “run 1 5”)
  4. Click “Create”

Deleting an Alias:

  1. Click on an alias to select it (button turns green)
  2. Press d or click “Delete Selected”

Keyboard shortcuts:

  • a: Add new alias
  • d: Delete selected alias
  • Escape or b: Go back

Example Display:

┌─────────────────────────────────────────────────────────────┐
│ ChatrixCD                                                   │
└─────────────────────────────────────────────────────────────┘

Command Aliases

Press 'a' to add, 'd' to delete. Only valid !cd commands can be aliased.

Current Aliases:

  ┌───────────────────────────────────────────────────────────┐
  │    deploy-prod → run 1 5                                  │
  └───────────────────────────────────────────────────────────┘
  
  ┌───────────────────────────────────────────────────────────┐
  │    🚀 → run 1 5                                           │
  └───────────────────────────────────────────────────────────┘
  
  ┌───────────────────────────────────────────────────────────┐
  │    health → ping                                          │
  └───────────────────────────────────────────────────────────┘

Actions:
  ┌───────────────────────────────────────────────────────────┐
  │    Add Alias [a]                                          │
  └───────────────────────────────────────────────────────────┘
  
  ┌───────────────────────────────────────────────────────────┐
  │    Delete Selected [d]                                    │
  └───────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ escape Back                                                 │
└─────────────────────────────────────────────────────────────┘

Note: Alias names with special characters including emoji (e.g., 🚀, 😱) are fully supported.

SAY

Send a message from the bot to a room:

  1. Select a room from dropdown
  2. Type your message
  3. Click “Send” button
Send Message

Select Room:
┌─────────────────────────────────────────────────────────────┐
│ Choose a room                                            ▼  │
└─────────────────────────────────────────────────────────────┘

Message:
┌─────────────────────────────────────────────────────────────┐
│ Type your message here...                                   │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                         Send                                │
└─────────────────────────────────────────────────────────────┘

LOG

Displays the last 1000 lines of the bot log in a scrollable text area. Most recent messages appear at the top for easier access to current activity:

Log View

┌─────────────────────────────────────────────────────────────┐
│ 2025-10-12 01:15:30 - INFO - Message from @user:matrix.org│
│ 2025-10-12 01:15:25 - INFO - Joined room !abc:matrix.org  │
│ 2025-10-12 01:15:24 - INFO - Connected to Matrix          │
│ 2025-10-12 01:15:23 - INFO - ChatrixCD starting...        │
│ ...                                                          │
│                                                              │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Keyboard shortcuts:

  • Escape or b: Go back
  • Arrow Keys or Mouse Wheel: Scroll through logs

SET

Change operational variables interactively. Allows editing any configuration setting:

Matrix Configuration:

  • homeserver, user_id, device_id, device_name
  • auth_type, password, oidc_redirect_url
  • store_path

Semaphore Configuration:

  • url, api_token, ssl_verify

Bot Configuration:

  • command_prefix
  • allowed_rooms, admin_users
  • greetings_enabled, greeting_rooms
  • startup_message, shutdown_message

Features:

  • Interactive editing with type validation
  • Pending changes preview with sensitive value redaction
  • Apply changes to runtime (temporary) or save to config.json (persistent)
  • Discard changes option
  • Keyboard shortcuts: a (Apply), s (Save), d (Discard)

Changes can be applied immediately or saved to config.json.

SHOW

Displays current configuration with sensitive credentials redacted:

Current Configuration

┌─────────────────────────────────────────────────────────────┐
│ {                                                            │
│   "matrix": {                                                │
│     "homeserver": "https://matrix.example.com",              │
│     "user_id": "@chatrixcd:example.com",                     │
│     "auth_type": "password",                                 │
│     "password": "***REDACTED***"                             │
│   },                                                         │
│   "semaphore": {                                             │
│     "url": "https://semaphore.example.com",                  │
│     "api_token": "***REDACTED***"                            │
│   },                                                         │
│   "bot": {                                                   │
│     "command_prefix": "!cd",                                 │
│     "admin_users": ["@admin:matrix.org"]                     │
│   }                                                          │
│ }                                                            │
└─────────────────────────────────────────────────────────────┘

QUIT

Gracefully shuts down the bot:

  1. Stops processing new messages
  2. Sends shutdown message to greeting rooms (if configured)
  3. Closes connections
  4. Exits the TUI

Keyboard Shortcuts

  • q or Ctrl+C: Quit the TUI
  • s: Show bot status
  • a: View admin users
  • r: Show joined rooms
  • e: Session management
  • x: Manage command aliases
  • m: Send message to room (Say)
  • l: View log
  • t: Change operational variables (Set)
  • c: Show current configuration
  • Escape or b: Go back to previous screen
  • Enter: Select/activate button
  • Tab: Navigate between elements
  • Arrow Keys: Navigate menu items

SET Menu Shortcuts

  • a: Apply changes (runtime only)
  • s: Save changes to config.json
  • d: Discard pending changes
  • Escape or b: Go back

Mouse Support

The TUI fully supports mouse interaction:

  • Click buttons to activate them
  • Click menu items to select them
  • Use scroll wheel to scroll through logs and lists
  • Drag to select text (in log and config views)

Color Support

When using the -C flag, the TUI displays in brand colors:

  • Header: ChatrixCD green (#3e836b / RGB: 74, 155, 127) background with white text
  • Footer: Dark background (#2D3238 / RGB: 45, 50, 56)
  • Primary Buttons: ChatrixCD green background
  • Text: Standard terminal colors
  • Status: Color-coded status indicators

Color Translation: The Textual framework automatically translates HTML hex colors to appropriate terminal colors based on your terminal’s capabilities:

  • True color (24-bit) terminals: Exact RGB colors
  • 256-color terminals: Closest match from 256-color palette
  • 16-color terminals: Closest match from basic 16 colors

Without the -C flag, the TUI remains fully functional using monochrome colors.

System Requirements

  • Python 3.12 or higher (3.12, 3.13, 3.14 supported)
  • Terminal with support for:
    • UTF-8 encoding
    • ANSI escape sequences (for colors with -C)
    • Mouse events (optional, but recommended)

Running Without TUI

To run ChatrixCD without the TUI (classic log-only mode):

chatrixcd -L

The TUI is automatically disabled when:

  • Running in daemon mode (-D)
  • Running in a non-interactive terminal (e.g., piped output)
  • The -L or --log-only flag is used

Troubleshooting

TUI Not Starting

If the TUI doesn’t start:

  1. Ensure you’re running in an interactive terminal
  2. Check that the terminal supports ANSI escape sequences
  3. Try running with -L flag to use log-only mode
  4. Check for error messages in the log

Display Issues

If the TUI displays incorrectly:

  1. Resize your terminal window
  2. Try running without colors (chatrixcd without -C)
  3. Ensure your terminal is UTF-8 compatible
  4. Check terminal size (minimum 80x24 recommended)

Mouse Not Working

If mouse clicks don’t work:

  1. Use keyboard shortcuts instead:
    • Main menu: s, a, r, e, m, l, t, c, q
    • Navigation: Tab, Enter, Arrow keys, Escape, b
    • SET menu: a (Apply), s (Save), d (Discard)
  2. Check if your terminal emulator supports mouse events
  3. Try a different terminal emulator

Advanced Features

Real-Time Task Monitoring

The main menu now includes a real-time active tasks display that shows:

  • All currently running Semaphore tasks
  • Task IDs and project IDs
  • Current status with color-coded indicators:
    • 🔄 Running (yellow)
    • ✅ Success (green)
    • ❌ Error/Stopped (red)
    • ⏸️ Unknown/Pending (blue)

The display updates automatically every 5 seconds, providing live feedback on CI/CD operations without needing to manually check task status.

Active Tasks

  🔄 Task 123 (Project 1): running
  ✅ Task 122 (Project 2): success

Session Verification (Encryption)

The TUI now includes comprehensive device verification features for end-to-end encryption:

Emoji Verification

Full interactive emoji verification using the Matrix SDK:

  1. Select “Verify Device (Emoji)” from the Sessions menu
  2. Choose an unverified device from the list
  3. The bot initiates SAS (Short Authentication String) verification
  4. Compare the displayed emoji sequence (7 emojis) with the other device
  5. If they match, click “✅ Yes, they match” to confirm verification
  6. If they don’t match, click “❌ No, they don’t match” to reject
  7. Upon confirmation, devices exchange and verify MAC codes automatically

Features:

  • Uses Matrix SDK’s native SAS verification protocol
  • Real emoji sequences generated from shared secrets
  • Automatic MAC exchange and verification
  • Works with any Matrix client that supports emoji verification
  • Permanent device verification (persisted across sessions)

QR Code Verification

Generate and scan QR codes for quick device verification:

  1. Select “Verify Device (QR Code)” from the Sessions menu
  2. A QR code is generated containing your device information
  3. Scan with another device to verify your bot’s identity
  4. The QR code includes:
    • User ID
    • Device ID
    • Verification timestamp

Device Fingerprint

View and share your device’s Ed25519 fingerprint for manual verification:

  1. Select “Show Fingerprint” from the Sessions menu
  2. Share the fingerprint with trusted parties
  3. Use for out-of-band verification

Encryption Sessions List

View all active encryption sessions:

  • User IDs and device IDs
  • Device names
  • Verification status (✅ verified / ⚠️ unverified)

Interactive Configuration Editing

The SET menu now provides full interactive configuration editing for all configuration settings:

Editable Sections

Matrix Configuration:

  • matrix.homeserver - Matrix homeserver URL
  • matrix.user_id - Bot user ID
  • matrix.device_id - Device identifier
  • matrix.device_name - Human-readable device name
  • matrix.auth_type - Authentication type (password/oidc)
  • matrix.password - Password for password auth
  • matrix.oidc_redirect_url - Redirect URL for OIDC auth (optional)
  • matrix.store_path - Path to encryption store

Semaphore Configuration:

  • semaphore.url - Semaphore UI URL
  • semaphore.api_token - Semaphore API token
  • semaphore.ssl_verify - SSL certificate verification

Bot Configuration:

  • bot.command_prefix - Command prefix (e.g., !cd)
  • bot.allowed_rooms - List of allowed room IDs
  • bot.admin_users - List of admin user IDs
  • bot.greetings_enabled - Enable/disable greetings
  • bot.greeting_rooms - Rooms for greetings
  • bot.startup_message - Bot startup message
  • bot.shutdown_message - Bot shutdown message
  • bot.log_file - Path to log file

Edit Workflow

  1. Press t or select “SET - Change operational variables”
  2. Choose a variable to edit from the list
  3. Enter the new value (with type validation)
  4. Choose action:
    • Apply Changes (Runtime Only) or press a: Changes take effect immediately but are lost on restart
    • Save to config.json or press s: Changes are persisted to disk and survive restarts
    • Discard Changes or press d: Abandon all pending modifications

Safety Features

  • Type validation ensures correct data types (string, integer, boolean, list)
  • Preview pending changes before applying with sensitive value redaction
  • Separate runtime and persistent save operations
  • Graceful error handling with user-friendly messages
  • Keyboard shortcuts for faster operation

Screenshots 

╔═══════════════════════════════════════════════════════════════╗
║ ChatrixCD                                                     ║
╚═══════════════════════════════════════════════════════════════╝

                       ChatrixCD
            Matrix CI/CD Bot - Interactive Interface

Active Tasks

  🔄 Task 123 (Project 1): running
  ✅ Task 122 (Project 2): success

 ┌───────────────────────────────────────────────────────────┐
 │        STATUS - Show bot status                           │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │        SESSIONS - Session management                      │
 └───────────────────────────────────────────────────────────┘
 
 [Additional menu options...]

Session Management Menu 

╔═══════════════════════════════════════════════════════════════╗
║ ChatrixCD                                                     ║
╚═══════════════════════════════════════════════════════════════╝

                   Session Management

 ┌───────────────────────────────────────────────────────────┐
 │    View Encryption Sessions                               │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │    Verify Device (Emoji)                                  │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │    Verify Device (QR Code)                                │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │    Show Fingerprint                                       │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │    Reset Olm Sessions                                     │
 └───────────────────────────────────────────────────────────┘

QR Code Verification 

╔═══════════════════════════════════════════════════════════════╗
║ ChatrixCD                                                     ║
╚═══════════════════════════════════════════════════════════════╝

                  QR Code Verification

Scan this QR code with the other device:

████████████████████████████████
██          ██  ██  ██        ██
██  ██████  ██  ████  ██████  ██
██  ██████  ██      ██  ██  ████
██  ██████  ████████████  ██  ██
██          ██  ██  ██  ████  ██
████████████████████████████████

Device: ABCDEFGH
User: @chatrixcd:example.com

Note: The other device needs to scan this QR code
to verify this bot's identity.

Configuration Editor 

╔═══════════════════════════════════════════════════════════════╗
║ ChatrixCD                                                     ║
╚═══════════════════════════════════════════════════════════════╝

              Set Operational Variables

Select a variable to edit:

Matrix Configuration:
 ┌───────────────────────────────────────────────────────────┐
 │    matrix.homeserver                                      │
 └───────────────────────────────────────────────────────────┘
 ┌───────────────────────────────────────────────────────────┐
 │    matrix.user_id                                         │
 └───────────────────────────────────────────────────────────┘
 [... more matrix options ...]

Semaphore Configuration:
 ┌───────────────────────────────────────────────────────────┐
 │    semaphore.url                                          │
 └───────────────────────────────────────────────────────────┘
 [... more semaphore options ...]

Bot Configuration:
 ┌───────────────────────────────────────────────────────────┐
 │    bot.command_prefix                                     │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │    bot.greetings_enabled                                  │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │    bot.startup_message                                    │
 └───────────────────────────────────────────────────────────┘
 [... more bot options ...]

Actions:
 ┌───────────────────────────────────────────────────────────┐
 │    Apply Changes (Runtime Only)                      [a]  │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │    Save to config.json                               [s]  │
 └───────────────────────────────────────────────────────────┘
 
 ┌───────────────────────────────────────────────────────────┐
 │    Discard Changes                                   [d]  │
 └───────────────────────────────────────────────────────────┘

Pending Changes:
  • bot.command_prefix = !bot
  • bot.greetings_enabled = false
  • matrix.password = ***REDACTED***

Future Enhancements

Additional features planned for future releases:

  • Task history and logs viewer
  • Performance metrics and graphs
  • Dark/light theme toggle
  • Custom color schemes
  • Bulk device verification
  • Advanced encryption session management