ChatrixCD Text User Interface (TUI)
Overview
ChatrixCD includes a Text User Interface (TUI) that provides an interactive, menu-driven way to manage and monitor the bot. The TUI is built using the Textual framework and features:
- Menu-driven navigation
- Mouse support
- Brand colors (ChatrixCD green: #4A9B7F)
- Real-time status updates
- Log viewing
- Configuration display
- Room messaging
Starting the TUI
The TUI launches automatically when running ChatrixCD in an interactive terminal:
chatrixcd
To enable colored output:
chatrixcd -C
To run without the TUI (classic log-only mode):
chatrixcd -L
TUI Interface
Main Menu
┌─────────────────────────────────────────────────────────────┐
│ ChatrixCD │
└─────────────────────────────────────────────────────────────┘
ChatrixCD
Matrix CI/CD Bot - Interactive Interface
┌─────────────────────────────────────────────────────────┐
│ STATUS - Show bot status │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ ADMINS - View admin users │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ ROOMS - Show joined rooms │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ SESSIONS - Session management │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ SAY - Send message to room │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ LOG - View log │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ SET - Change operational variables │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ SHOW - Show current configuration │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ QUIT - Exit │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ q Quit │
└─────────────────────────────────────────────────────────────┘
Menu Options
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)
SAY
Send a message from the bot to a room:
- Select a room from dropdown
- Type your message
- 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:
- Stops processing new messages
- Sends shutdown message to greeting rooms (if configured)
- Closes connections
- Exits the TUI
Keyboard Shortcuts
Main Menu Shortcuts
- q or Ctrl+C: Quit the TUI
- s: Show bot status
- a: View admin users
- r: Show joined rooms
- e: Session management
- m: Send message to room (Say)
- l: View log
- t: Change operational variables (Set)
- c: Show current configuration
Global Navigation
- 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 (#4A9B7F / 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.9 or higher
- 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:
- Ensure you’re running in an interactive terminal
- Check that the terminal supports ANSI escape sequences
- Try running with
-L
flag to use log-only mode - Check for error messages in the log
Display Issues
If the TUI displays incorrectly:
- Resize your terminal window
- Try running without colors (
chatrixcd
without-C
) - Ensure your terminal is UTF-8 compatible
- Check terminal size (minimum 80x24 recommended)
Mouse Not Working
If mouse clicks don’t work:
- 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)
- Check if your terminal emulator supports mouse events
- 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:
- Select “Verify Device (Emoji)” from the Sessions menu
- Choose an unverified device from the list
- The bot initiates SAS (Short Authentication String) verification
- Compare the displayed emoji sequence (7 emojis) with the other device
- If they match, click “✅ Yes, they match” to confirm verification
- If they don’t match, click “❌ No, they don’t match” to reject
- 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:
- Select “Verify Device (QR Code)” from the Sessions menu
- A QR code is generated containing your device information
- Scan with another device to verify your bot’s identity
- The QR code includes:
- User ID
- Device ID
- Verification timestamp
Device Fingerprint
View and share your device’s Ed25519 fingerprint for manual verification:
- Select “Show Fingerprint” from the Sessions menu
- Share the fingerprint with trusted parties
- 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 URLmatrix.user_id
- Bot user IDmatrix.device_id
- Device identifiermatrix.device_name
- Human-readable device namematrix.auth_type
- Authentication type (password/oidc)matrix.password
- Password for password authmatrix.oidc_redirect_url
- Redirect URL for OIDC auth (optional)matrix.store_path
- Path to encryption store
Semaphore Configuration:
semaphore.url
- Semaphore UI URLsemaphore.api_token
- Semaphore API tokensemaphore.ssl_verify
- SSL certificate verification
Bot Configuration:
bot.command_prefix
- Command prefix (e.g.,!cd
)bot.allowed_rooms
- List of allowed room IDsbot.admin_users
- List of admin user IDsbot.greetings_enabled
- Enable/disable greetingsbot.greeting_rooms
- Rooms for greetingsbot.startup_message
- Bot startup messagebot.shutdown_message
- Bot shutdown messagebot.log_file
- Path to log file
Edit Workflow
- Press t or select “SET - Change operational variables”
- Choose a variable to edit from the list
- Enter the new value (with type validation)
- 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
Main Menu with Active Tasks
╔═══════════════════════════════════════════════════════════════╗
║ 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