TUI

TUI (Terminal User Interface) Mode provides a modern, visually rich terminal interface for agentic development and other tasks.

Activation

The TUI is the default in current versions of Cecli and on older versions it can be started explicitly in the terminal with:

cecli ... --tui

Configuration

The TUI can be configured directly in the relevant config.json file or with JSON in the command line arguments:

Minimal Configuration

tui: true

Complete Configuration Example

The base theme is pretty nice but if you want different colors and key bindings, you can specify them in the configuration files (~/.cecli/conf.yml or .cecli.conf.yml):

tui: true
tui-config:
  colors:
    primary: "#00ff5f"
    secondary: "#888888"
    accent: "#00ff87"
    foreground: "#ffffff"
    background: "#1e1e1e"
    success: "#00aa00"
    warning: "#ffd700"
    error: "#ff3333"
    surface: "transparent"
    panel: "transparent"
    input-cursor-foreground: "#00ff87"
  other:
    dark: true
    input-cursor-text-style: "underline"
    use_terminal_background: false
  key_bindings:
    newline: "shift+enter"
    submit: "enter"
    completion: "tab"
    stop: "escape"
    editor: "ctrl+o"
    history: "alt+shift+h"
    voice: "ctrl+r"
    paste: "alt+v"
    cycle_forward: "tab"
    cycle_backward: "shift+tab"
    input_start: "ctrl+home"
    input_end: "ctrl+end"
    output_up: "shift+pageup"
    output_down: "shift+pagedown"
    focus: "ctrl+f"
    cancel: "ctrl+c"
    clear: "ctrl+l"
    quit: "ctrl+q"
    next_agent: "alt+ctrl+right"
    prev_agent: "alt+ctrl+left"
    main_agent: "alt+ctrl+home"
    panel_up: "alt+ctrl+up"
    panel_down: "alt+ctrl+down"
    panel_cycle: "alt+o"

Key Command Configuration

The TUI provides customizable key bindings for all major actions. The default key bindings are:

Floating Panels

Press alt+o or run /open commands to open the background command panel. It floats centered over the TUI, leaving the rest of the interface visible, and shows the output of active background shell commands. Tabs labelled with each command’s background key switch between commands, the line below the tabs shows the full command, and f toggles tail-following the output. Press escape to close it.

alt+o cycles through the available panel types. When the last panel type is open, pressing alt+o again closes it.

Customizing Key Bindings

You can customize any key binding by adding a key_bindings section to your tui-config. For example, to change the quit key to ctrl+x:

tui-config:
  key_bindings:
    quit: "ctrl+x"

All key bindings use Textual’s key syntax:

• Single keys: enter, escape, tab
• Modifier combinations: ctrl+c, shift+tab, etc.

Warning: key bindings may not work if they conflict with the textual library defaults at:

Textual Documentation

Benefits

• Improved Productivity: Reduced context switching with all information visible at once
• Better Organization: Clear separation of concerns between input, output, and status
• Enhanced Readability: Proper formatting and syntax highlighting for code discussions
• Real-time Feedback: Immediate visual feedback for all operations
• Modern Interface: Familiar UI patterns that reduce cognitive load
• Accessibility: Full keyboard navigation without requiring mouse interaction

Integration with Other Modes

TUI Mode works seamlessly with other cecli features:

• Agent Mode: Visual feedback for tool calls and autonomous operations
• Skills: Clean display of skill outputs and interactions
• MCP Servers: Integrated display of MCP tool outputs
• Git Operations: Real-time git status updates in the footer

Legacy Mode

For an interactive session without the full-screen TUI, use this canonical
profile in ~/.cecli/conf.yml or .cecli.conf.yml:

tui: false
linear-output: true
fancy-input: true
stream: true

This keeps the sophisticated prompt_toolkit input editor, including history
and completion, while making output unsophisticated and sequential. Streaming
responses remain enabled, but Cecli does not redraw earlier application output.
That linear application-output stream contains no cursor-motion or erasure
sequences, and a carriage return appears only immediately before a line feed as
part of a CRLF line ending. The input editor may still use terminal controls
while editing the current prompt.

This conservative output profile is useful over SSH, in limited terminals, and
when preserving output in logs or passing it through scripts and pipes. Cecli
automatically disables fancy input when it detects a dumb terminal. For other
terminals that cannot reliably support prompt_toolkit, set
fancy-input: false.

Troubleshooting

Common Issues

1. TUI not starting: Ensure your terminal supports True Color (24-bit color)
2. Display issues: Try resizing your terminal window
3. Performance problems: Reduce terminal refresh rate or disable animations
4. Input lag: Check for conflicts with terminal multiplexers (tmux, screen)

Reduce Motion

Set Textual’s native animation level in your shell or .env file to keep the
TUI static while preserving status updates:

TEXTUAL_ANIMATIONS=none

To hide only the activity spinner, use --no-spinner or set spinner: false
in a Cecli configuration file.

Terminal Requirements

• True Color Support: Required for proper color rendering
• Minimum Size: 80x24 terminal size recommended
• Unicode Support: Required for proper symbol display
• Modern Terminal: Recommended: Kitty, WezTerm, iTerm2, or Windows Terminal