TUI Guide

TUI Mode

Current status: The TUI launches and displays a device list. Full interactive features (sorting, vim keys, mouse, details panel) are in progress.

Launch the interactive Terminal User Interface by running Device Finder without arguments:

df

Keyboard controls:

Key	Action
`↑` / `↓`	Navigate devices
`Tab`	Cycle platform filters (All → iOS → Android → Web → All)
`r`	Refresh device list
`q` / `Esc`	Quit

Device List View

The TUI displays devices in a table format:

Device Finder
┌─────────────────────────────────────────────────────────┐
│ PLATFORM NAME                TYPE         STATUS   ID   │
├─────────────────────────────────────────────────────────┤
│ iOS      iPhone 16 Pro       Simulator    Shutdown ABC.. │
│ Android  Pixel 9             Emulator     Connected ... │
│ iOS      iPad Air 6          Simulator    Connected ... │
└─────────────────────────────────────────────────────────┘
↑↓: Navigate | Tab: Filter | r: Refresh | q: Quit

Features

Real-time refresh: Press r to reload the device list
Platform filtering: Press Tab to filter by iOS, Android, Web, or show all
Color indicators: Device status is color-coded for quick scanning
- 🟢 Green: Connected/Running
- ⚫ Dark Gray: Shutdown/Offline
- 🟡 Yellow: Booting/Loading
- ⚪ Gray: Unknown/Unavailable

Tips

Use Tab repeatedly to quickly switch between platform views
Press r to refresh if you just connected a new device

Combine TUI with CLI commands for scripting:

# Get device list from TUI view, then use in CLI
df find "iPhone" --json

Performance

The TUI loads devices on startup. On systems with many devices, initial load may take a few seconds.

Initial load: 1–2s (macOS with iOS simulators), 2–5s (Android with active emulators)
Refresh (r): Same as initial load
Navigation: Instant

Basic Movement

Key	Action
`↑` / `↓`	Navigate up/down one row
`j` / `k`	Vim-style navigation
`Page Up`	Move up 10 rows
`Page Down`	Move down 10 rows
`Home`	Jump to first device
`End`	Jump to last device
`g`	Jump to top
`G`	Jump to bottom

Filtering & Sorting

Key	Action
`Tab`	Cycle platform filter (All → iOS → Android → Web → All)
`s`	Change sort column (cycles: name → platform → status → type → OS)
`S` (shift+s)	Toggle sort direction (ascending ↔ descending)

Application Control

Key	Action
`r`	Refresh device list
`q`	Quit TUI

Mouse Support

The TUI supports mouse interaction:

Scroll wheel: Navigate up/down through the list
Trackpad scroll: Smooth scrolling navigation

Note: Click selection is not currently implemented. Use keyboard for precise selection.

Color Coding

Platform Colors

Platform	Color	Emoji
iOS	Blue	📱
Android	Green	🤖
Web	Cyan	🌐
Unknown	Gray	❓

Status Colors

Status	Color	Meaning
Connected	🟢 Green	Device is running
Shutdown	⚫ Dark Gray	Device is off
Not Installed	🟡 Yellow	Runtime not available
Booting	🟡 Yellow	Device starting
Unknown	⚪ Gray	Status unavailable

Selection Highlight

Selected row: Light blue background with black text
Cursor indicator: ▶ arrow at row start
Scrollbar thumb: Light blue on dark track

Sorting Behavior

When sorting, devices are reorganized while maintaining your selection context:

Press s to cycle through sort columns
Press S to reverse direction
Selection is preserved when possible
Scroll position adjusts to keep selected device visible

Sort Columns

Column	Sort Logic
Name	Alphabetical
Platform	iOS → Android → Web → Unknown
Status	Connected → Booting → Shutdown → Unknown
Type	Simulator → Emulator → Physical → Container
OS Version	Semantic version (18.2 < 18.4)

Tips & Tricks

Quick Filtering

Use Tab to quickly isolate a platform:

Starting from [All], one Tab shows only iOS
Two Tabs shows only Android
Three Tabs shows only Web
Four Tabs returns to [All]

Finding Specific Devices

Sort by name (s until "name" appears)
Use g to go to top
Use G to go to end
Or navigate with arrow keys

Large Device Lists

When you have many simulators:

Use Page Up/Page Down for faster navigation
The scrollbar shows your position in the list
Status bar shows "X/Y devices" counter

Refresh After Changes

If you:

Create a new simulator in Xcode
Start an Android emulator
Connect a physical device

Press r to refresh the list without restarting the TUI.

Troubleshooting

TUI Won't Launch

Check terminal requirements:

Terminal must support alternate screen buffer
Unicode support required for table borders
Minimum 80x24 terminal size recommended

Colors Look Wrong

Ensure your terminal supports 256 colors:

# Check color support
echo $TERM
# Should show xterm-256color or similar

# If not, set in your shell config:
export TERM=xterm-256color

Mouse Scrolling Not Working

Mouse support requires:

Terminal with mouse reporting (most modern terminals)
No terminal multiplexer capturing events (tmux/screen may interfere)
In tmux: set -g mouse on

High CPU Usage

The TUI polls for input every 50ms. This should be negligible, but if you notice high CPU:

Ensure you're running a release build (cargo build --release)
Check for terminal rendering issues with your terminal emulator

Configuration

The TUI currently uses sensible defaults. Future versions may support:

Custom color schemes
Configurable key bindings
Default sort preferences
Column visibility toggles

Comparison: TUI vs CLI

Feature	CLI	TUI
Speed	Instant	~100ms startup
Interaction	One-shot	Continuous
Visualization	Text table	Rich columns
Sorting	Flags	Interactive
Filtering	Flags	Real-time
Details	Per-command	Persistent panel
Best for	Scripts, CI	Exploration, debugging