tui-reference.md

TUI Reference Guide

GhostScope's TUI interface consists of three panels with distinct functionality. This guide focuses on keyboard shortcuts and panel operations.

Quick Reference

• Global Shortcuts: Work across all panels
• Panel 1: Source Code Panel - Navigate and set trace points
• Panel 2: eBPF Output Panel - View real-time trace output
• Panel 3: Command Interaction Panel - Execute commands and edit scripts

Global Shortcuts

Important: These shortcuts only work when the Command Interaction Panel is focused and in Command Mode (not Input Mode or Script Mode).

Shortcut	Function	Description
Tab	Switch Panel	Cycle forward: Source → eBPF → Command
Shift+Tab	Reverse Switch	Cycle backward through panels
Ctrl+W + h/j/k/l	Vim Navigation	Jump to left/down/up/right panel
Ctrl+W + z or F1	Toggle Fullscreen	Fullscreen current panel or restore
Ctrl+W + v or F2	Toggle Layout	Switch panel layout arrangement
Ctrl+C (twice)	Quit	Press twice to exit GhostScope

Ctrl+C Behavior

• First Press:
  • Script Mode: Cancel script editing
  • Other modes: Show "Press Ctrl+C again to exit"
• Second Press: Exit program

Window Navigation Mode

Press Ctrl+W, then:

• h: Jump to left panel
• j: Jump to bottom panel
• k: Jump to top panel
• l: Jump to right panel
• v: Toggle layout
• z: Toggle fullscreen

---

Panel 1: Source Code Panel

Displays source code with trace point management. Operates in three modes: Normal, Text Search, and File Search.

Mode: Normal

Basic Navigation

Shortcut	Function
h/j/k/l	Vim navigation (left/down/up/right)
↑/↓/←/→	Arrow key navigation
Ctrl+U	Scroll up 10 lines (half page)
Ctrl+D	Scroll down 10 lines (half page)
PgUp/PgDn	Full page scroll
gg	Jump to file start
G	Jump to file end
[number]G	Jump to specific line (enter number then G)

Vim-style Word Movement

Shortcut	Function
w	Next word beginning
b	Previous word beginning
^	Line start (first non-blank character)
$	Line end

Mode Switching

Shortcut	Function
/	Enter Text Search mode
o	Enter File Search mode
Space	Set trace point at current line → Enter Script Mode

Mode: Text Search

Search for text within the current file.

Shortcut	Function
[char]	Type to build search query
n	Next search match
N	Previous search match
Esc or Ctrl+C	Exit to Normal mode

Mode: File Search

Search and quickly switch between source files. File list comes from all source files in DWARF debug information.

Search & Filtering

Shortcut	Function
[char]	Type to filter file list (real-time filtering)
Backspace	Delete character from search query
Ctrl+U	Clear entire search query
Ctrl+W	Delete previous word

Notes:

• Substring matching: Type any part to match (e.g., nginx matches /path/to/nginx.c)
• Path search: Search in paths (e.g., core/nginx matches src/core/nginx.c)
• Real-time filtering: File list updates as you type
• Shows up to 10 matching results

Navigation & Selection

Shortcut	Function
↓ or Ctrl+N	Select next file
↑ or Ctrl+P	Select previous file
Enter	Open selected file
Esc or Ctrl+C	Cancel and return to Normal mode

Cursor Control

Shortcut	Function
Ctrl+A	Move cursor to beginning of search input
Ctrl+E	Move cursor to end of search input
Ctrl+B or ←	Move cursor left one character
Ctrl+F or →	Move cursor right one character

Tips:

• File list shares cache with command panel's file completion, automatically updates when srcpath mappings change
• If file paths cannot be found, use srcpath map command to configure path mappings (see input-commands.md)

---

Panel 2: eBPF Output Panel

Displays real-time trace events as cards. Two display modes: Auto-Refresh (default) and Scroll (manual navigation).

Carded Output and Expanded View

• Each event renders as a card with header and body.
• In list view, each card shows up to 3 wrapped lines; if truncated, a bold yellow … appears at the end of line 3.
• Press Enter to expand the selected card. In expanded view: j/k/↑/↓ scroll, Ctrl+U/D half-page, PgUp/PgDn page, Esc or Ctrl+C to close.

Basic Navigation

Shortcut	Function
j or ↓	Scroll down (enters Scroll mode)
k or ↑	Scroll up (enters Scroll mode)
h or ←	Scroll left
l or →	Scroll right
Ctrl+D	Half page down
Ctrl+U	Half page up
PgUp/PgDn	Full page scroll
g or gg	Jump to oldest trace (top)
G	Jump to latest trace (bottom, returns to Auto-Refresh mode)
[number]G	Jump to specific line (enter number then G)

Display Modes

• Auto-Refresh Mode (default): Automatically shows latest traces, auto-scrolls
• Scroll Mode: Enter by pressing j, k, or other navigation keys; allows manual browsing of trace history

---

Panel 3: Command Interaction Panel

Supports three interaction modes: Input Mode, Command Mode, and Script Mode.

Mode Overview

Mode	Purpose	Entry	Exit
Input Mode	Execute commands	i (from Command Mode)	Esc or jk
Command Mode	Browse command history	Esc or jk (from Input Mode)	i
Script Mode	Edit trace scripts	After trace command	Ctrl+S (submit) or Ctrl+C (cancel)

Mode: Input Mode

Execute commands and use command completion. See Input Mode Commands for detailed command reference.

Input & Editing

Shortcut	Function
[char]	Type characters
Backspace or Ctrl+H	Delete character before cursor
Ctrl+W	Delete previous word
Ctrl+U	Delete to line start
Ctrl+K	Delete to line end
Enter	Execute command

Cursor Movement

Shortcut	Function
← or Ctrl+B	Move cursor left
→ or Ctrl+F	Move cursor right
Ctrl+A	Move to line start
Ctrl+E	Move to line end

Command Completion & Suggestions

Shortcut	Function
Tab	Auto-complete command or filename
→ or Ctrl+E	Accept auto-suggestion (gray text)

History Navigation

Shortcut	Function
↑ or Ctrl+P	Previous command
↓ or Ctrl+N	Next command
Ctrl+R	Start history search mode

History Search Sub-mode

After pressing Ctrl+R:

Shortcut	Function
[char]	Type to search history
Backspace	Delete character from search query
Ctrl+R	Next matching command
Enter	Execute matched command
Esc	Use matched command as input (exit search)
Ctrl+C	Cancel and clear input

Mode Switching

Shortcut	Function
Esc or jk	Enter Command Mode (jk must be pressed within 150ms)

Mode: Command Mode

Browse and navigate command history with Vim-style navigation.

Navigation

Shortcut	Function
h/j/k/l	Navigate left/down/up/right through history
Ctrl+U	Half page up
Ctrl+D	Half page down
g or gg	Jump to top of history
G	Jump to bottom of history

Mode Switching

Shortcut	Function
i	Return to Input Mode

Mode: Script Mode

Edit trace scripts with syntax highlighting after executing trace command.

Features:

• Real-time syntax highlighting for GhostScope script language
• Line numbers with current line emphasis
• Multi-line editing support
• Automatic script caching per target (restored on re-entry)

Text Editing

Shortcut	Function
[char]	Type characters
Backspace or Ctrl+H	Delete character before cursor
Ctrl+W	Delete previous word
Ctrl+U	Delete to line start
Ctrl+K	Delete to line end
Enter	Insert new line
Tab	Insert 4 spaces (indent)

Cursor Movement

Shortcut	Function
← or Ctrl+B	Move cursor left
→ or Ctrl+F	Move cursor right
↑ or Ctrl+P	Move to previous line
↓ or Ctrl+N	Move to next line
Ctrl+A	Move to line start
Ctrl+E	Move to line end

Script Control

Shortcut	Function
Ctrl+S	Submit script (compile and load)
Ctrl+C or Esc	Cancel script edit and return to Input Mode

---

Tips

1. Quick Tracing: Press Space in Source Panel for fastest trace point setup
2. Vim Navigation: Master h/j/k/l keys for efficient navigation
3. Command Completion: Use Tab frequently to reduce typing
4. History Search: Press Ctrl+R in Input Mode for reverse history search
5. Fullscreen Focus: Use Ctrl+W z when you need to concentrate on one panel

Related Documentation

• Input Mode Commands - Detailed command reference for Input Mode
• Script Language - Trace script syntax and examples
• Configuration - Customize TUI behavior
• Quick Tutorial - Step-by-step getting started guide