# What Is the Purpose of the `--perfect` Flag in llmfit?

> Understand the purpose of the --perfect flag in llmfit. Filter for models with perfect hardware fit, ensuring exact or ample RAM/VRAM match for your system specs.

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

---

**The `--perfect` flag in `llmfit` filters the output of the `fit` sub-command to show only models whose hardware fit level is "Perfect"—meaning their RAM/VRAM requirements exactly match or comfortably exceed the detected system specs.**

`llmfit` analyzes how well Large Language Model (LLM) configurations align with your machine's available resources. The tool assigns every model a **fit level** on a tiered scale: **Perfect > Good > Marginal > TooTight**. This ranking helps users quickly identify which models will run optimally versus those that might strain or exceed hardware limits. The `--perfect` flag provides a targeted view of only the top-tier matches.

## How the `--perfect` Flag Works

The flag is implemented as a boolean CLI argument in the Clap definition for the `fit` sub-command. You can find this in [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) within the `Commands::Fit` variant.

When you invoke `llmfit fit --perfect`, the core analysis pipeline proceeds through these stages:

1. **Analysis**: `ModelFit::analyze()` evaluates all models against detected hardware specs
2. **Filtering**: The `filter::perfect_only` function retains only entries with `fit_level == FitLevel::Perfect`
3. **Rendering**: Results display sorted by score, limited to perfect matches

This filter operates on the `fit_level` field of each `ModelFit` instance, as defined in [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs).

### Behavior Comparison

| Scenario | Without `--perfect` | With `--perfect` |
|----------|---------------------|------------------|
| Models shown | All compatible models regardless of fit quality | Only models with `Perfect` fit level |
| Ranking | Sorted by score, includes Good/Marginal/TooTight entries | Sorted by score, restricted to optimal matches |
| Best used for | Exploring full compatibility range | Finding ideal hardware matches quickly |

## Practical Usage Examples

### Show All Compatible Models (Default)

```bash

# List top 10 models of any fit level

llmfit fit -n 10

```

### Show Only Perfect-Fit Models

```bash

# List top 5 models with optimal hardware match

llmfit fit --perfect -n 5

```

### Combine with Other Options

```bash

# Limit context window and filter to perfect matches

llmfit --max-context 8192 fit --perfect -n 3

```

The flag composes naturally with global options like `--max-context` and standard flags like `-n` (limit results).

## Key Implementation Files

Understanding the `--perfect` flag requires familiarity with these source files:

- **[`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs)** — Defines the Clap CLI structure and wires the `--perfect` boolean flag to the `fit` sub-command execution
- **[`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs)** — Contains the `FitLevel` enum (`Perfect`, `Good`, `Marginal`, `TooTight`) and the `filter::perfect_only` logic that enforces the flag's behavior
- **[`docs/cli.md`](https://github.com/AlexsJones/llmfit/blob/main/docs/cli.md)** — Documents command-line usage patterns including `--perfect` examples
- **[`README.md`](https://github.com/AlexsJones/llmfit/blob/main/README.md)** — Provides quick-start examples demonstrating typical `--perfect` workflows

## When to Use `--perfect`

Use this flag when you want to:

- **Eliminate noise** by hiding suboptimal matches
- **Prioritize stability** by selecting models with guaranteed headroom
- **Automate selection** in scripts that need reliable, non-marginal candidates
- **Benchmark confidently** knowing hardware limits won't throttle performance

Skip the flag when exploring edge cases, testing borderline configurations, or investigating why a seemingly compatible model receives a lower fit score.

## Summary

- The `--perfect` flag restricts `llmfit fit` output to models with `FitLevel::Perfect` hardware compatibility
- Implementation spans [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) (CLI definition) and [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs) (filter logic)
- Without the flag: all fit levels shown; with the flag: optimal matches only
- Combines with standard options like `-n` and `--max-context` for precise result control

## Frequently Asked Questions

### What fit levels does llmfit recognize?

`llmfit` evaluates models against four tiers: **Perfect** (ideal match), **Good** (comfortable fit), **Marginal** (tight but functional), and **TooTight** (exceeds available resources). These are defined in the `FitLevel` enum in [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs).

### Does `--perfect` affect how models are scored or just displayed?

The flag only filters displayed results. The underlying `ModelFit::analyze()` method computes scores and fit levels identically regardless of flags. The `filter::perfect_only` function applies after analysis completes.

### Can I use `--perfect` with other sub-commands besides `fit`?

No. The `--perfect` flag is defined exclusively for the `fit` sub-command in [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs). Other sub-commands like `list` or `info` do not expose this option.

### What makes a model "Perfect" versus "Good"?

A **Perfect** fit means the model's RAM and VRAM requirements fall comfortably within detected hardware with substantial headroom. **Good** fits still run reliably but with less margin for system overhead or memory spikes. The exact thresholds are computed in the core analysis logic.