llmfit TUI vs CLI Mode: What Is the Difference and When to Use Each

llmfit provides two front-end modes in a single binary: CLI mode for scripting and one-shot commands, and TUI mode for interactive exploration with a full-screen terminal interface.

Both modes execute identical core analysis logic in llmfit-core, differing only in how results are presented to the user. Understanding when to use each mode helps you integrate llmfit into automation pipelines or leverage its visual tools for manual hardware sizing sessions.

How to Launch Each llmfit Mode

The entry point for both modes is llmfit-tui/src/main.rs, which parses flags and dispatches to the appropriate handler.

CLI Mode Invocation

Add the --cli flag to skip the TUI and print results directly:

# Default table output

llmfit --cli fit --perfect -n 5

# JSON for scripting

llmfit --cli fit --json --limit 3

# CSV for spreadsheet import

llmfit --cli fit --csv -n 10

TUI Mode Invocation

Omit the flag to start the interactive interface:

cargo run

# or after installation

llmfit

User Interface Architecture

CLI Mode: Static Output Generation

In CLI mode, llmfit-tui/src/display.rs handles all rendering. It formats model-fit results as plain text without dependencies on terminal UI libraries.

Supported output formats:

• --table – formatted ASCII tables (default)
• --json – machine-parseable JSON arrays
• --csv – comma-separated values

CLI mode exits immediately after printing, making it suitable for Unix pipelines and CI/CD jobs.

TUI Mode: Interactive Terminal UI

TUI mode activates a ratatui-based full-screen interface coordinated across three modules:

Module	Responsibility
tui_app.rs	Application state management
tui_ui.rs	Widget layout and rendering
tui_events.rs	Keyboard input handling and state mutations

The event loop in tui_events.rs enables:

• / – open live search/filter bar
• ←/→ – navigate between Results, Plans, and Diagnostics tabs
• s – cycle export formats (table/JSON/CSV) without exiting
• q or Esc – quit and return to shell

Interactivity Comparison

Feature	CLI Mode	TUI Mode
Execution model	One-shot, exits immediately	Persistent, event-driven loop
Navigation	None – linear output	Scroll, search, tab switching
Real-time updates	N/A	Live hardware monitoring
Filter application	Pre-run via flags (--perfect, -n 5)	Interactive toggles and search

Performance Characteristics

CLI mode avoids the initialization cost of crossterm and ratatui, yielding marginally faster cold-start times. For typical workloads—fitting against model databases of hundreds to thousands of entries—this difference is negligible.

TUI mode incurs a small fixed overhead for terminal setup (cursor hiding, alternate screen buffer) and hat widget tree construction in tui_ui.rs. The tradeoff is justified for exploratory sessions where iterative filtering outpaces repeated CLI invocations.

Shared Core Analysis

Both modes delegate to identical backend logic in llmfit-core:

• llmfit-core/src/analysis.rs – model capability scoring
• llmfit-core/src/fit.rs – hardware-to-model matching algorithms

This ensures consistent results regardless of front-end choice. The main.rs dispatcher merely selects between display.rs (CLI) and the TUI module trilogy after flag parsing completes.

Typical Use Cases

Choose CLI mode when:

• Integrating into shell scripts or Makefiles
• Running in CI/CD pipelines without TTY access
• Generating JSON/CSV for downstream tools
• Executing predefined queries repeatedly

Choose TUI mode when:

• Exploring unfamiliar model databases
• Comparing multiple fit scenarios visually
• Monitoring hardware constraints in real time
• Exporting results after interactive refinement

Summary

• llmfit TUI vs CLI mode differ only in presentation—both use llmfit-core for calculations.
• CLI mode (--cli) routes through display.rs for immediate, scriptable output.
• TUI mode (default) launches a ratatui interface with search, tabs, and live filtering.
• Dispatch occurs in llmfit-tui/src/main.rs based on flag presence.
• Performance gap is minimal; select based on workflow needs.

Frequently Asked Questions

What is the default mode when running llmfit without flags?

The TUI mode launches by default. Executing llmfit or cargo run without --cli initializes the full-screen interactive interface defined in tui_app.rs, tui_ui.rs, and tui_events.rs.

Can I export data from TUI mode?

Yes. Press s inside the TUI to cycle between table, JSON, and CSV export formats. The underlying serialization logic mirrors display.rs used in CLI mode.

Is the analysis logic different between modes?

No. Both front-ends call identical functions in llmfit-core/src/analysis.rs and fit.rs. The main.rs dispatcher ensures the same hardware-to-model matching runs regardless of interface choice.

Why does CLI mode exist if TUI is the default?

CLI mode supports non-interactive environments like CI systems, cron jobs, and containerized deployments where no TTY is available. The explicit --cli flag guarantees exit codes and stdout behavior suitable for automation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}