Complete Guide to WhichLLM CLI Commands: Usage and Examples

The whichllm CLI provides six commands—default, plan, upgrade, run, snippet, and hardware—declared in 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 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 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.

# Display top models for your current machine

$ whichllm

This command leverages src/whichllm/hardware/detector.py for system analysis and 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, this helps you verify hardware compatibility before downloading.

# 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, reports the best-ranked models for each hypothetical configuration.

# 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, it handles both GGUF and Transformers models, automatically installing dependencies via uv when needed.

# 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, this outputs ready-to-run code without external dependencies.

# 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, it supports GPU simulation via flags.

# 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: Detects host CPU, RAM, OS, and GPU specifications
• src/whichllm/models/fetcher.py: Retrieves model metadata from HuggingFace
• src/whichllm/models/benchmark.py: Pulls benchmark scores used for ranking calculations
• src/whichllm/engine/ranker.py: Implements the ranking algorithm powering the default and upgrade commands
• 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 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. This automatically detects your system hardware using 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.

How does the plan command determine GPU requirements?

The plan command queries model metadata via src/whichllm/models/fetcher.py to calculate the GPU resources needed for a specific model. Located around line 5055 in 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, it uses 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, 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.

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