# Complete Guide to WhichLLM CLI Commands: Usage and Examples

> Discover WhichLLM CLI commands like default, plan, upgrade, run, snippet, and hardware. Learn hardware detection, model ranking, and interactive execution with this comprehensive guide.

- Repository: [andy/whichllm](https://github.com/Andyyyy64/whichllm)
- Tags: how-to-guide
- Published: 2026-06-10

---

**The `whichllm` CLI provides six commands—default, `plan`, `upgrade`, `run`, `snippet`, and `hardware`—declared in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py) using Typer, enabling hardware detection, model ranking, and interactive execution.**

The `whichllm` package from the Andyyyy64/whichllm repository delivers a comprehensive command-line interface built on **Typer** to help you identify and run optimal LLMs for your specific hardware. Understanding the available WhichLLM CLI commands allows you to detect system capabilities, compare model requirements, simulate upgrades, and launch interactive sessions without manual configuration.

## Overview of the WhichLLM CLI Architecture

All WhichLLM CLI commands are registered in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py) through Typer decorators. The application uses a modular architecture where hardware detection, model fetching, benchmark scoring, and ranking operate as distinct components.

The entry point `app` object in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py) registers commands via `@app.command()` decorators, while the default callback uses `@app.callback` at line 196 to execute when no subcommand is provided.

## Available WhichLLM CLI Commands

The interface exposes six distinct commands covering the complete LLM selection workflow.

### Default Command (Hardware Detection and Ranking)

When invoked without subcommands, `whichllm` acts as the default entry point that automatically detects your hardware and displays top-ranked models. This callback is defined via `@app.callback` at line 196 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py).

```bash

# Display top models for your current machine

$ whichllm

```

This command leverages [`src/whichllm/hardware/detector.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/hardware/detector.py) for system analysis and [`src/whichllm/engine/ranker.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/engine/ranker.py) for scoring.

### plan Command

The `plan` command reveals GPU resource requirements for specific models or HuggingFace repositories. Implemented via `@app.command()` around line 5055 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py), this helps you verify hardware compatibility before downloading.

```bash

# Check GPU requirements for a specific model

$ whichllm plan "mistralai/Mixtral-8x7B-Instruct-v0.1"

```

### upgrade Command

Use `upgrade` to simulate hardware configurations by comparing your current system against target GPUs. This command, located around line 6444 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py), reports the best-ranked models for each hypothetical configuration.

```bash

# Compare current hardware against potential upgrades

$ whichllm upgrade "RTX 4090" "RTX 5090" --cpu-only

```

### run Command

The `run` command automates model acquisition and launches interactive chat sessions. Found at line 8780 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py), it handles both GGUF and Transformers models, automatically installing dependencies via `uv` when needed.

```bash

# Download and start chatting with the best model automatically

$ whichllm run

```

### snippet Command

Generate standalone Python scripts for embedding models into your projects using the `snippet` command. Located around line 10222 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py), this outputs ready-to-run code without external dependencies.

```bash

# Generate a Python script for a specific model

$ whichllm snippet "Qwen/2.5-7B-Instruct"

```

### hardware Command

The `hardware` command provides detailed system diagnostics including CPU, RAM, OS, and GPU specifications. Implemented around line 10999 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py), it supports GPU simulation via flags.

```bash

# Display detected hardware or simulate a specific GPU

$ whichllm hardware --gpu "RTX 4090" --vram 24

```

## Supporting Infrastructure

The WhichLLM CLI relies on several specialized modules that work together to provide end-to-end functionality:

- **[`src/whichllm/hardware/detector.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/hardware/detector.py)**: Detects host CPU, RAM, OS, and GPU specifications
- **[`src/whichllm/models/fetcher.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/models/fetcher.py)**: Retrieves model metadata from HuggingFace
- **[`src/whichllm/models/benchmark.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/models/benchmark.py)**: Pulls benchmark scores used for ranking calculations
- **[`src/whichllm/engine/ranker.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/engine/ranker.py)**: Implements the ranking algorithm powering the default and `upgrade` commands
- **[`src/whichllm/output/display.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/output/display.py)**: Formats hardware info, rankings, and JSON output

## Summary

- **Six primary commands**: default, `plan`, `upgrade`, `run`, `snippet`, and `hardware`
- **All commands registered** in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py) using Typer's `@app.command()` decorator, with the default callback at line 196
- **Complete workflow coverage**: from hardware detection (`hardware`, default) to compatibility checking (`plan`), upgrade simulation (`upgrade`), code generation (`snippet`), and execution (`run`)
- **Modular architecture**: Hardware detection, model fetching, benchmarking, and ranking operate as separate components in `src/whichllm/`

## Frequently Asked Questions

### What is the default behavior when running `whichllm` without arguments?

When executed without subcommands, `whichllm` triggers the default callback defined with `@app.callback` at line 196 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py). This automatically detects your system hardware using [`src/whichllm/hardware/detector.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/hardware/detector.py) and displays the top-ranked models for your specific configuration based on benchmark scores from [`src/whichllm/models/benchmark.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/models/benchmark.py).

### How does the `plan` command determine GPU requirements?

The `plan` command queries model metadata via [`src/whichllm/models/fetcher.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/models/fetcher.py) to calculate the GPU resources needed for a specific model. Located around line 5055 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py), this command analyzes the model's parameters and architecture to report whether your current hardware (or a specified configuration) can run the model efficiently.

### Can I simulate different hardware configurations without physically changing my GPU?

Yes, the `upgrade` command allows you to simulate arbitrary hardware configurations by specifying target GPUs as arguments. Implemented around line 6444 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py), it uses [`src/whichllm/engine/ranker.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/engine/ranker.py) to compare your current system against hypothetical setups and reports the best-ranked models for each scenario.

### How does the `run` command handle model dependencies?

The `run` command, found at line 8780 in [`src/whichllm/cli.py`](https://github.com/Andyyyy64/whichllm/blob/main/src/whichllm/cli.py), automatically manages dependencies for both GGUF and Transformers models. It installs required packages on-the-fly using `uv` and handles the entire download and initialization process, launching an interactive chat session immediately after preparation.