# How to Use llmfit in CLI Mode: Command-Line Interface Guide

> Master llmfit CLI mode. Run analysis directly in your terminal with fit, recommend, or info subcommands for efficient data processing. Get table or JSON output now.

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

---

**Run `llmfit` with the `--cli` flag or any subcommand like `fit`, `recommend`, or `info` to bypass the TUI and execute analysis directly in your terminal with table or JSON output.**

The `llmfit` binary from the [AlexsJones/llmfit](https://github.com/AlexsJones/llmfit) repository ships with a full-screen TUI by default, but you can invoke the same analysis engine from a traditional command-line interface. When you use llmfit in CLI mode, the tool shares the core hardware detection and model-fit logic with the TUI, swapping the interactive presentation layer for simple table or JSON output suitable for scripts and automation.

## Activating CLI Mode

The application detects CLI mode through a command-dispatch block in [[`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs)](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs). When the binary sees the global flag `--cli` **or** any recognized subcommand (`fit`, `recommend`, `info`, `system`), it bypasses the TUI startup and executes the selected command directly.

The `Cli` struct defined at lines 14-71 uses `clap` derive macros to parse global flags including memory overrides, output formats, and context limits. The dispatch logic at lines 40-44 routes execution to the appropriate handler based on whether you provided a subcommand or the standalone `--cli` flag.

```bash

# Launch classic CLI mode without subcommand (shows table of all models)

llmfit --cli

# Use a specific subcommand (automatically activates CLI mode)

llmfit fit --perfect -n 5
llmfit recommend --json --limit 5

```

## Core Architecture and Execution Flow

When running in CLI mode, the application follows a consistent pipeline defined in the core library:

1. **Hardware Detection**: The system queries `SystemSpecs::detect()` from [[`llmfit-core/src/hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs)](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs) to gather RAM, CPU cores, and GPU VRAM statistics.

2. **Model Catalog Loading**: The engine initializes `ModelDatabase::new()` to load the built-in model definitions and apply any custom overrides from configuration files.

3. **Fit Analysis**: Each candidate model passes through `ModelFit::analyze_with_forced_runtime()` implemented in [[`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs)](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs). This computes memory fit, estimated throughput, quality scores, and context suitability.

4. **Output Rendering**: Results flow to the classic formatter in [[`llmfit-tui/src/display.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/display.rs)](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/display.rs) (lines 781-788), which constructs the terminal table or JSON envelope based on your flags.

## Available Subcommands

The CLI supports several subcommands that map directly to analysis operations documented in [[`docs/cli.md`](https://github.com/AlexsJones/llmfit/blob/main/docs/cli.md)](https://github.com/AlexsJones/llmfit/blob/main/docs/cli.md):

- **`fit`**: Analyze model compatibility against your hardware and display fit rankings.
- **`recommend`**: Show top recommendations filtered by use-case (e.g., coding, creative writing).
- **`info`**: Display detailed specifications for a specific model.
- **`system`**: Dump detected system specifications (useful for debugging).

```bash

# Show only perfectly-fitting models, limited to top 5

llmfit fit --perfect -n 5

# Get JSON recommendations for coding use-case

llmfit recommend --json --use-case coding --limit 3

# Dump system specs as JSON for bug reports

llmfit --json system

```

## Global Flags and Hardware Overrides

Global flags defined at lines 103-119 of [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) work identically in both TUI and CLI modes. You can override auto-detected hardware values or adjust analysis parameters:

- **`--memory`**: Override GPU VRAM detection (e.g., `--memory=32G`)
- **`--ram`**: Override system RAM detection
- **`--cpu-cores`**: Override CPU core count
- **`--max-context`**: Cap the context length used for memory estimation (e.g., `--max-context 4096`)

```bash

# Override detected GPU VRAM and query fit

llmfit --memory=32G --cli fit -n 10

# Cap context length for conservative estimates

llmfit --max-context 4096 --cli fit --perfect

```

## Output Formats

The CLI supports three output formats controlled by flags:

- **Table** (default): Human-readable aligned columns suitable for terminal inspection.
- **JSON** (`--json`): Machine-parseable output ideal for shell scripts and CI/CD pipelines.
- **CSV** (`--csv`): Comma-separated values for spreadsheet import.

The formatting logic in [`llmfit-tui/src/display.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/display.rs) handles serialization differences between these modes while preserving the underlying data structures from the core analysis engine.

```bash

# JSON output for scripting

llmfit recommend --json --limit 5

# CSV export for analysis

llmfit fit --csv -n 20

```

## Summary

- **Use the `--cli` flag** or any subcommand (`fit`, `recommend`, `info`, `system`) to activate classic CLI mode instead of the TUI.
- **Hardware overrides** (`--memory`, `--ram`, `--cpu-cores`) and context limits (`--max-context`) function identically in both modes.
- **Core analysis** runs through `SystemSpecs::detect()` and `ModelFit::analyze_with_forced_runtime()` regardless of interface choice.
- **Output options** include human-readable tables, JSON for automation, and CSV for data analysis.

## Frequently Asked Questions

### What is the difference between CLI mode and TUI mode in llmfit?

CLI mode executes a single command and exits immediately, outputting results as text, JSON, or CSV to stdout. TUI mode launches an interactive full-screen interface where you can browse models, adjust filters, and explore recommendations in real-time. Both modes use identical hardware detection and model-fitting logic from the `llmfit-core` crate.

### Can I override the auto-detected hardware specifications?

Yes. Pass `--memory`, `--ram`, or `--cpu-cores` flags with your desired values to override what `SystemSpecs::detect()` returns. This is useful for testing hypothetical configurations or correcting detection errors without modifying the source code in [`llmfit-core/src/hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs).

### How do I integrate llmfit into shell scripts?

Use the `--json` flag combined with subcommands like `recommend` or `fit`. JSON output streams to stdout with stable keys, making it parseable with tools like `jq`. For example: `llmfit recommend --json --limit 5 | jq '.[].model_name'`.

### Why does my subcommand automatically activate CLI mode even without `--cli`?

The argument parser in [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) (lines 40-44) treats any subcommand presence as an explicit request for CLI execution. This design ensures that scripted invocations like `llmfit fit` never accidentally spawn the interactive TUI in non-interactive environments.