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

> Explore llmfit TUI vs CLI modes. Discover when to use the interactive terminal interface for exploration or command line for scripting and one-shot commands.

- Repository: [Alex Jones/llmfit](https://github.com/AlexsJones/llmfit)
- Tags: how-to-guide
- Published: 2026-08-20

---

**`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`](https://github.com/AlexsJones/llmfit/blob/main/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:

```bash

# 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:

```bash
cargo run

# or after installation

llmfit

```

## User Interface Architecture

### CLI Mode: Static Output Generation

In CLI mode, [`llmfit-tui/src/display.rs`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/tui_app.rs) | Application state management |
| [`tui_ui.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_ui.rs) | Widget layout and rendering |
| [`tui_events.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_events.rs) | Keyboard input handling and state mutations |

The event loop in [`tui_events.rs`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/analysis.rs) – model capability scoring
- [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs) – hardware-to-model matching algorithms

This ensures **consistent results** regardless of front-end choice. The [`main.rs`](https://github.com/AlexsJones/llmfit/blob/main/main.rs) dispatcher merely selects between [`display.rs`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/tui_app.rs), [`tui_ui.rs`](https://github.com/AlexsJones/llmfit/blob/main/tui_ui.rs), and [`tui_events.rs`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/analysis.rs) and [`fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/fit.rs). The [`main.rs`](https://github.com/AlexsJones/llmfit/blob/main/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.