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

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 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). 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.

# 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) 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). 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) (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):

• 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).

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

# 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 handles serialization differences between these modes while preserving the underlying data structures from the core analysis engine.

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

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 (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.

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