linux-doctor

linux-doctor [options]

linux-doctor runs read-only health checks on a Linux system, surfaces issues that actually matter, and explains each finding in plain language with a suggested fix. It is a diagnostic, not a monitor: it answers "what is wrong right now?" instead of streaming metrics.A full report leads with a START HERE next action, a health score from 0 to 100, a trend sparkline of recent runs, and a NEW/FIXED/unchanged diff against the previous run. Findings carry a stable `code` (`check/reason`), a severity, evidence from the system, and a copy-paste fix.Checks cover memory and swap pressure, load, disk and inode usage, filesystem errors, software RAID, OOM kills, failed systemd units, TLS certificate expiry, exposed ports, journal errors, containers, crash and reboot history, firewall and SSH posture, network and DNS, time sync, package and firmware updates, SMART health, GPU and thermal state, backups, and more. Checks that do not apply (battery on a desktop, reboot on an immutable image) are skipped and listed honestly.The CLI never modifies the system unless --fix --yes is given. --fix alone prints a dry-run plan from a small built-in catalog mapped to finding codes; free-text suggestions in the report are never executed. The same check engine also powers --web and an optional Tauri desktop app.

--check id

Run only the given check(s). Repeat the flag or pass a comma-separated list.

List available checks by category without running them.

List checks as JSON (id, title, category, appliesTo).

Machine-readable JSON output (schema version 1).

Plain, tab-separated text with no colors or emoji. Metadata is `#` comment lines.

One-liner with score, severity counts, and delta versus the previous run.

Write a Markdown report. IPs, home paths, and UIDs are redacted.

Write a standalone HTML report.

Numbered, copy-pasteable list of fix steps in priority order.

Dry run: print safe-fix commands from the built-in catalog. Nothing is executed.

Execute catalog [apply] commands. [manual] items are printed, never run.

Interactive terminal UI over the report. Needs a TTY; otherwise prints the normal report.

Send a desktop notification (`notify-send`) when new medium or high findings appear.

Open the visual dashboard in a browser on 127.0.0.1.

Explain the environment: distro, profile, which checks run, and why others are skipped.

Guided first-run setup: starter config, daily timer, and a notification test.

Create a starter config file with commented thresholds.

Install a user-level systemd timer (no sudo) that runs daily with --notify.

Remove and disable the timer installed by --install-timer.

Do not read or write run history for this run.

Clear stored run history.

Diff a previous JSON report against the current run.

Show only findings at this severity: high, medium, or info.

Hide findings whose title contains text (this run only).

Hide findings by stable code (for example `services/failed`).

Persistently ignore a code or title fragment (saved to config).

Remove a previously ignored code or title fragment.

Show configured ignore patterns and exit.

Write a privacy-scrubbed support bundle for bug reports.

Print the JSON Schema for --json output and exit.

Append per-check durations to the report.

Trace every spawned command and its result to stderr.

Add an AI summary in plain English (needs LLM_API_KEY). Finding text is scrubbed first.

Same as --ai, but use a local Ollama model (no cloud).

Post the report to a fleet server (FLEET_API_KEY optional).

Allow --push, --alert, --heartbeat, and --ai to target private or LAN addresses.

POST a webhook when the machine degrades (Pro).

Ping a dead-man's switch after every run (Pro).

Run continuously, re-checking every --interval (Pro).

Seconds between --daemon runs (default 3600). Pro.

Show Pro add-on status and exit.

Show usage.

Show the version number.

~/.config/linux-doctor/config.json holds optional ignore / ignoreCodes lists and a thresholds object. Every threshold key is optional; unset keys keep desktop defaults (disk 90/80 percent, memory available ratio 0.15/0.25, load per core, CPU temperature, journal size, container storage, DNS latency, certificate lifetime, backup staleness, and others).

$ linux-doctor --init-config

Write a starter file with commented thresholds.

$ linux-doctor --ignore-add [services/failed]

Persistently hide a finding by code or title fragment.

$ linux-doctor --thresholds-json

Print current thresholds and defaults.

0

No high or medium severity findings.

At least one high or medium severity finding.

Usage or runtime error (bad flags, unknown check, and similar).

~/.config/linux-doctor/config.json

Ignore patterns and threshold overrides. Override path with LINUX_DOCTOR_CONFIG.

Drop-in plugin checks (`.js` files). Override with LINUX_DOCTOR_PLUGINS.

Run history used for the health-score trend and NEW/FIXED diffs. Override with LINUX_DOCTOR_HISTORY.

Cache for the package-updates check (about 30 minutes). Override with LINUX_DOCTOR_CACHE.

LINUX_DOCTOR_CONFIG

Path to the configuration file.

Path to the history file.

Directory of plugin checks.

Directory for the updates cache.

When set, do not read or write history (same as --no-history).

When set to 1, trace spawned commands to stderr (same as --debug).

Path to a Node.js interpreter (desktop packages bundle their own).

API key for --ai cloud summaries.

Optional bearer token for --push.

The npm CLI needs Node.js 20 or newer. Packaged `.deb`, `.rpm`, and AppImage builds of the desktop app embed a Node runtime so nothing extra is required on PATH.Checks are read-only. --fix --yes only runs catalog [apply] entries; enabling a firewall, package autoremove, container prune, and trash deletion stay [manual]. Review the dry-run plan first.SMART and some security probes need root or extra tools (`smartctl`). Without them the check is skipped rather than reported as healthy. Immutable/atomic distros skip checks that cannot be acted on locally (notably reboot).--ai and fleet --push send scrubbed finding text off-box. Private or LAN destinations are refused unless --allow-private-endpoint is passed. --web binds to loopback.Exit status 1 means findings exist, not that the tool failed. Use 2 for errors in scripts.

Linux Doctor is a Node.js diagnostics CLI by zShaD0w7x, first released in August 2026 (GPL-3.0-or-later, with an optional commercial/Pro add-on). Version 0.6.0 (2026-09-13) added a bundled Node runtime in the desktop packages, auto-update for the AppImage, --debug command tracing, and --allow-private-endpoint.

inxi(1), journalctl(1), systemctl(1), smartctl(8), df(1), free(1), glances(1)

Source code · Documentation