# How to Use `llmfit doctor` for Hardware Detection Reports in LLMFit

> Learn how to use llmfit doctor to generate detailed hardware detection reports. Get system info, GPU details, and runtime data formatted for GitHub issues.

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

---

**The `llmfit doctor` command generates a comprehensive, Markdown-formatted hardware detection report by running system tools, detecting GPUs via vendor-specific utilities, and gathering runtime information—all ready to paste into GitHub issues.**

If you're troubleshooting GPU detection or runtime compatibility in the [AlexsJones/llmfit](https://github.com/AlexsJones/llmfit) project, `llmfit doctor` is your first diagnostic step. This built-in sub-command produces a reproducible dump of your system's hardware configuration and every external tool used during detection, formatted specifically for bug reports.

---

## What `llmfit doctor` Does

Running `llmfit doctor` executes a six-stage diagnostic pipeline defined in [[`llmfit-core/src/doctor.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/doctor.rs)](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/doctor.rs). Here's exactly what happens:

1. **Version & OS Collection** – Captures the binary version, operating system, and architecture.
2. **System Specs Detection** – Invokes `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, and GPU details.
3. **External Tool Execution** – Shells out to vendor-specific utilities including `nvidia-smi`, `rocm-smi`, `lspci`, `system_profiler` (macOS), PowerShell WMI queries, `vulkaninfo`, and `npu-smi`.
4. **Sysfs/Registry Reading** – Accesses `/sys/class/drm/*` on Linux or Windows registry keys for VRAM information.
5. **Runtime Detection** – Checks for LM Studio, Docker Desktop, and whether `ollama` is available on `PATH`.
6. **Markdown Assembly** – Each section is wrapped with `## Section Name` headers and fenced code blocks via the `section()` helper at line 54.

The `capture()` helper (lines 15-38) manages each external call, capturing both stdout and stderr while safely truncating output to 16 KB per section to prevent oversized reports.

---

## Running `llmfit doctor` from the Command Line

### Basic Terminal Output

View the report directly in your terminal:

```bash
llmfit doctor

```

You'll see output structured like this:

```markdown

# llmfit doctor report

...

## Detected by llmfit

[Structured hardware information]

## nvidia-smi

[Raw command output]

```

### Save to File for Bug Reports

Redirect the output to a file for later inspection or GitHub issues:

```bash
llmfit doctor > llmfit-doctor.md

```

The resulting file is ready to paste into the bug report template's diagnostic field.

---

## Using `llmfit doctor` Programmatically

You can invoke the same diagnostic collection from Rust code. The CLI entry point 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) uses this exact pattern at line 2817:

```rust
use llmfit_core::doctor::collect_diagnostics;

fn main() {
    let report = collect_diagnostics(env!("CARGO_PKG_VERSION"));
    println!("{}", report);
}

```

The `env!("CARGO_PKG_VERSION")` macro automatically propagates your binary's version into the report header, ensuring reproducibility across different builds.

---

## Submitting Reports to GitHub Issues

The [`.github/ISSUE_TEMPLATE/bug-report.yml`](https://github.com/AlexsJones/llmfit/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml) file in the repository includes a dedicated field for diagnostic output. After running `llmfit doctor > llmfit-doctor.md`:

1. Open the generated file
2. Copy the entire contents
3. Paste into the "Diagnostic report (`llmfit doctor`)" field

This gives maintainers complete visibility into:
- Which detection tools succeeded or failed
- Raw GPU driver output
- Runtime environment state

---

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [`llmfit-core/src/doctor.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/doctor.rs) | Core implementation of report generation and external tool orchestration |
| [`llmfit-core/src/hardware.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/hardware.rs) | `SystemSpecs::detect()` implementation for RAM/CPU/GPU detection |
| [`llmfit-tui/src/main.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/main.rs) | CLI routing at line 2817 that forwards to `collect_diagnostics` |
| [`docs/cli.md`](https://github.com/AlexsJones/llmfit/blob/main/docs/cli.md) | Official CLI documentation including `llmfit doctor` usage |
| [`.github/ISSUE_TEMPLATE/bug-report.yml`](https://github.com/AlexsJones/llmfit/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml) | Bug report template with diagnostic field |

---

## Summary

- **`llmfit doctor`** is the canonical command for hardware detection reports in LLMFit
- Reports are **Markdown-native** and structured for immediate GitHub issue inclusion
- The command runs **8+ external detection tools** across NVIDIA, AMD, Intel, and Apple Silicon platforms
- Output is **automatically truncated** to 16 KB per section for manageable report sizes
- Use `collect_diagnostics()` directly in Rust programs for custom integrations

---

## Frequently Asked Questions

### What hardware detection tools does `llmfit doctor` run?

The command executes platform-specific utilities: `nvidia-smi` and `npu-smi` for NVIDIA devices, `rocm-smi` for AMD, `vulkaninfo` for Vulkan-compatible GPUs, `lspci` on Linux, `system_profiler` on macOS, and PowerShell WMI queries on Windows. Each tool's raw output appears in its own report section.

### Why is my `llmfit doctor` output truncated?

The `capture()` helper in [`doctor.rs`](https://github.com/AlexsJones/llmfit/blob/main/doctor.rs) enforces a 16 KB limit per section to prevent massive reports from overwhelming issue trackers. This threshold covers typical tool output while filtering runaway logs. If you need complete unfiltered output, run the individual detection commands manually.

### Can I run `llmfit doctor` without installing the full TUI?

Yes—`llmfit doctor` is a standalone function in `llmfit-core`. Any Rust program can import `llmfit_core::doctor::collect_diagnostics` and generate reports without the terminal interface, as shown in the programmatic example above.

### Where do I submit my `llmfit doctor` report?

Paste the complete output into the [`.github/ISSUE_TEMPLATE/bug-report.yml`](https://github.com/AlexsJones/llmfit/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml) template when filing issues on the [AlexsJones/llmfit](https://github.com/AlexsJones/llmfit) repository. The template includes a specific field labeled "Diagnostic report (`llmfit doctor`)" designed for this purpose.