micforge 1.3.0__py3-none-any.whl

micforge/cli.py

@@ -0,0 +1,293 @@
+"""Command-line entry point."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .config import AppConfig
+from .errors import MicforgeError
+from .logging_setup import setup_logging
+from .ui.theme import console
+
+
+def _device_arg(v: str):
+    return int(v) if v.isdigit() else v
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="micforge",
+        description="Real-time mic clean-up for Discord & co: de-muffle, denoise, level, route via a virtual cable.",
+    )
+    p.add_argument("-v", "--version", action="version", version=f"micforge {__version__}")
+    p.add_argument("--debug", action="store_true", help="verbose log file")
+    p.add_argument("--model", help="path to swappable CoFi-Lite model file (.onnx or .tar)")
+    p.add_argument("--tray", action="store_true", help="start live enhancer in background system tray mode")
+    sub = p.add_subparsers(dest="cmd")
+
+    r = sub.add_parser("run", help="live: mic -> processing -> virtual cable (what Discord hears)")
+    r.add_argument("-p", "--preset", help="DSP preset to load (e.g. streaming, gaming, podcast, noisy_room)")
+    r.add_argument("--mic", type=_device_arg, help="input device (index or name part)")
+    r.add_argument("--cable", type=_device_arg, help="virtual cable output (index or name part)")
+    r.add_argument("--monitor", nargs="?", const="", type=_device_arg, metavar="DEVICE",
+                   help="also play the processed mic to your headphones")
+    r.add_argument("--rate", type=int, help="sample rate (default from config: 48000)")
+    r.add_argument("--block", type=int, help="block size in samples (default 480)")
+    r.add_argument("--model", help="swappable CoFi-Lite model file (.onnx or .tar)")
+    r.add_argument("--tray", action="store_true", help="run in background with system tray icon")
+    r.add_argument("--no-tray", action="store_true", help="disable system tray icon")
+
+    l = sub.add_parser("loopback", help="hear yourself live through headphones, A/B raw vs processed")
+    l.add_argument("-p", "--preset", help="DSP preset to load (default: active preset)")
+    l.add_argument("--mic", type=_device_arg, help="input microphone (index or substring)")
+    l.add_argument("--out", type=_device_arg, help="headphones device (index or substring)")
+    l.add_argument("--model", help="swappable CoFi-Lite model file (.onnx or .tar)")
+
+    t = sub.add_parser("test", help="record a clip, show before/after analysis, play both back")
+    t.add_argument("-p", "--preset", help="DSP preset to test (default: active preset)")
+    t.add_argument("-s", "--seconds", type=float, default=8.0, help="duration in seconds to record sample")
+    t.add_argument("--mic", type=_device_arg, help="microphone device (index or substring)")
+    t.add_argument("--out", type=_device_arg, help="playback headphones device (index or substring)")
+    t.add_argument("--model", help="swappable CoFi-Lite model file (.onnx or .tar)")
+
+    c = sub.add_parser("calibrate", help="learn your room noise (improves denoise + sets the gate)")
+    c.add_argument("-s", "--seconds", type=float, default=4.0, help="duration in seconds of ambient silence to sample")
+    c.add_argument("--mic", type=_device_arg, help="microphone device (index or substring)")
+    c.add_argument("--reset", action="store_true", help="delete the saved noise profile")
+
+    d = sub.add_parser("devices", help="list audio devices")
+    d.add_argument("--all", action="store_true", help="show every host API (MME, DirectSound, ...)")
+
+    sub.add_parser("setup", help="choose mic / cable / headphones interactively")
+
+    # Preset management suite
+    p_cmd = sub.add_parser("preset", help="manage and create custom presets")
+    p_sub = p_cmd.add_subparsers(dest="preset_action")
+    p_sub.add_parser("list", help="list all presets")
+    p_save = p_sub.add_parser("save", help="create or save a custom preset")
+    p_save.add_argument("name", help="new preset name")
+    p_save.add_argument("--from", dest="from_preset", help="base preset to clone from")
+    p_save.add_argument("--desc", default="", help="human description for the preset")
+    p_save.add_argument("--force", action="store_true", help="overwrite if exists")
+    p_copy = p_sub.add_parser("copy", help="duplicate an existing preset")
+    p_copy.add_argument("source", help="source preset")
+    p_copy.add_argument("target", help="target new preset name")
+    p_copy.add_argument("--force", action="store_true", help="overwrite if exists")
+    p_del = p_sub.add_parser("delete", help="delete a custom preset")
+    p_del.add_argument("name", help="preset name to delete")
+    p_del.add_argument("-y", "--yes", action="store_true", help="skip confirmation")
+    p_exp = p_sub.add_parser("export", help="export preset to portable JSON")
+    p_exp.add_argument("name", help="preset to export")
+    p_exp.add_argument("target", nargs="?", help="output file path")
+    p_imp = p_sub.add_parser("import", help="import preset from JSON file")
+    p_imp.add_argument("source", help="path to preset JSON file")
+    p_imp.add_argument("--name", default=None, help="custom name for imported preset")
+    p_imp.add_argument("--force", action="store_true", help="overwrite if exists")
+    p_show = p_sub.add_parser("show", help="show preset details")
+    p_show.add_argument("name", help="preset name")
+
+    pr = sub.add_parser("presets", help="list presets, or print one as JSON (alias for `micforge preset`)")
+    pr.add_argument("name", nargs="?")
+
+    f = sub.add_parser("process", help="process a WAV file offline")
+    f.add_argument("input")
+    f.add_argument("output")
+    f.add_argument("-p", "--preset")
+    f.add_argument("--model", help="swappable CoFi-Lite model file (.onnx or .tar)")
+
+    a = sub.add_parser("analyze", help="analyse a WAV file (level, noise, clarity) and give advice")
+    a.add_argument("input")
+
+    m_cmd = sub.add_parser("model", help="inspect or export swappable CoFi-Lite models")
+    m_cmd.add_argument("action", choices=["info", "export"], nargs="?", default="info")
+    m_cmd.add_argument("checkpoint", nargs="?", help="source .tar / .pth checkpoint")
+    m_cmd.add_argument("output", nargs="?", help="output .onnx file")
+
+    doc = sub.add_parser("doctor", help="check your setup and performance (plain-English diagnostics)")
+    doc.add_argument("--export", nargs="?", const="", help="export diagnostic report as a redacted .zip bundle")
+
+    lat = sub.add_parser("latency", help="measure end-to-end audio pipeline latency with loopback probe")
+    lat.add_argument("--mic", type=_device_arg, help="input microphone device (index or substring)")
+    lat.add_argument("--out", type=_device_arg, help="output playback device (index or substring)")
+
+    prof = sub.add_parser("profile", help="manage noise profiles (quiet_room, fan_on, mechanical_keyboard)")
+    prof.add_argument("action", choices=["list", "show", "relearn", "switch"], default="list", nargs="?",
+                      help="profile action to perform (list, show, relearn, switch)")
+    prof.add_argument("name", nargs="?", help="profile / environment name")
+
+    sub.add_parser("version", help="show micforge version and system information")
+    sub.add_parser("settings", help="open GUI to customize global hotkeys, audio cues, and startup")
+    sub.add_parser("hotkeys", help="alias for settings")
+    help_p = sub.add_parser("help", help="show comprehensive command guide and dynamic usage examples")
+    help_p.add_argument("command", nargs="?", help="specific command to inspect (e.g. run, latency, profile, doctor)")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    setup_logging(args.debug)
+    try:
+        app = AppConfig.load()
+        cmd = args.cmd
+        model_arg = getattr(args, "model", None)
+        if model_arg:
+            app.denoise_model = model_arg
+        if cmd is None and getattr(args, "tray", False):
+            cmd = "run"
+        if cmd is None:
+            from .commands.wizard import run_wizard
+            run_wizard(app)
+        elif cmd == "version":
+            from . import __version__
+            from .dsp.cofilite import find_model_file
+            console.print(f"[bold cyan]micforge[/] [bold green]v{__version__}[/]")
+            active = find_model_file(app.denoise_model)
+            model_str = f"CoFi-Lite ({active.name})" if active else "Spectral Wiener"
+            console.print(f"  [dim]Active Model:[/] {model_str}")
+            console.print(f"  [dim]Python:[/] {sys.version.split()[0]} on {sys.platform}")
+            return 0
+        elif cmd == "run":
+            from .commands.live import run_live
+            if args.rate:
+                app.sample_rate = args.rate
+            if args.block:
+                app.block_size = args.block
+            app.validate()
+            run_live(app, preset=args.preset, monitor=args.monitor is not None, mic=args.mic, cable=args.cable,
+                     monitor_dev=(args.monitor or None) if args.monitor is not None else None,
+                     model=model_arg, tray=getattr(args, "tray", False), no_tray=getattr(args, "no_tray", False))
+        elif cmd == "loopback":
+            from .commands.live import run_live
+            run_live(app, preset=args.preset, loopback=True, mic=args.mic, monitor_dev=args.out, model=model_arg)
+        elif cmd == "test":
+            from .commands.test_mic import run_test
+            run_test(app, preset=args.preset, seconds=max(4.0, args.seconds), mic=args.mic, out=args.out)
+        elif cmd == "calibrate":
+            from .commands.calibrate import run_calibrate
+            run_calibrate(app, seconds=max(2.0, args.seconds), mic=args.mic, reset=args.reset)
+        elif cmd == "devices":
+            from .commands.devices_cmd import show_devices
+            show_devices(args.all)
+        elif cmd == "setup":
+            from .commands.devices_cmd import run_setup, show_devices
+            run_setup(app)
+        elif cmd in ("preset", "presets"):
+            from .commands.preset_cmd import (
+                run_preset_copy,
+                run_preset_delete,
+                run_preset_export,
+                run_preset_import,
+                run_preset_list,
+                run_preset_save,
+                run_preset_show,
+            )
+            action = getattr(args, "preset_action", None)
+            if cmd == "presets":
+                if args.name:
+                    run_preset_show(args.name)
+                else:
+                    run_preset_list(app)
+            elif action in (None, "list"):
+                run_preset_list(app)
+            elif action == "save":
+                run_preset_save(app, args.name, from_preset=args.from_preset, description=args.desc, force=args.force)
+            elif action == "copy":
+                run_preset_copy(args.source, args.target, force=args.force)
+            elif action == "delete":
+                run_preset_delete(args.name, force=args.yes)
+            elif action == "export":
+                run_preset_export(args.name, args.target)
+            elif action == "import":
+                run_preset_import(args.source, name=args.name, force=args.force)
+            elif action == "show":
+                run_preset_show(args.name)
+        elif cmd == "process":
+            from .commands.files import run_process
+            run_process(app, args.input, args.output, args.preset)
+        elif cmd == "analyze":
+            from .commands.files import run_analyze
+            run_analyze(app, args.input)
+        elif cmd == "model":
+            from pathlib import Path
+            from .dsp.cofilite import find_model_file
+            if args.action == "info":
+                active = find_model_file(model_arg or app.denoise_model)
+                if active and active.is_file():
+                    size_kb = active.stat().st_size / 1024
+                    console.print(f"[bold green]✔ Active CoFi-Lite model:[/] {active} ({size_kb:.1f} KB)")
+                    console.print("  [dim]Type:[/] ONNX neural speech enhancement (~83k params)")
+                    console.print("  [dim]Memory:[/] ~65-75 MB RAM (well under 100 MB limit)")
+                else:
+                    console.print("[yellow]! No CoFi-Lite model file found. Operating with fallback Spectral Wiener denoiser.[/]")
+            elif args.action == "export":
+                if not args.checkpoint:
+                    console.print("[red]✖ Please provide checkpoint path: micforge model export <checkpoint.tar> [out.onnx][/]")
+                    return 1
+                from .dsp.export_cofilite import export_checkpoint_to_onnx
+                target = args.output or Path(args.checkpoint).with_suffix(".onnx")
+                export_checkpoint_to_onnx(args.checkpoint, target)
+                console.print(f"[bold green]✔ Successfully exported CoFi-Lite model to:[/] {target}")
+        elif cmd == "doctor":
+            from .commands.doctor import run_doctor
+            export_flag = args.export is not None
+            export_path = args.export if (args.export and len(args.export) > 0) else None
+            return run_doctor(app, export=export_flag, export_path=export_path)
+        elif cmd == "latency":
+            from .commands.latency_test import run_latency_test
+            return run_latency_test(app, mic=args.mic, out=args.out)
+        elif cmd == "profile":
+            action = args.action or "list"
+            if action == "list":
+                from .audio.noise_profile import BUILTIN_ENVIRONMENTS, list_noise_profiles
+                profiles = list_noise_profiles()
+                console.print("\n[bold cyan]🎙️ Available Noise Profiles & Environments:[/]")
+                for p in profiles:
+                    tag = " [green](builtin)[/]" if p in BUILTIN_ENVIRONMENTS else " [dim](custom)[/]"
+                    console.print(f"  • [bold white]{p}[/]{tag}")
+                console.print("\n[dim]Usage: micforge profile switch <name>  │  micforge profile show <name>[/]\n")
+                return 0
+            elif action == "show":
+                from .audio.noise_profile import BUILTIN_ENVIRONMENTS, AdaptiveNoiseProfiler
+                prof_name = args.name or "quiet_room"
+                profiler = AdaptiveNoiseProfiler(sample_rate=app.sample_rate, environment=prof_name)
+                p = profiler.current_profile
+                console.print(f"\n[bold cyan]Noise Profile:[/] [bold green]{p.name}[/]")
+                console.print(f"  • Estimated Floor:    [yellow]{p.noise_floor_db:.1f} dBFS[/]")
+                console.print(f"  • Gate Threshold:     [yellow]{p.gate_threshold_db:.1f} dBFS[/]")
+                console.print(f"  • Spectral Tilt:      [dim]{p.spectral_tilt:+.2f}[/]")
+                console.print(f"  • Status:             {'[cyan]Frozen[/]' if p.frozen else '[green]Active Learner[/]'}\n")
+                return 0
+            elif action == "switch":
+                if not args.name:
+                    console.print("[red]✖ Please specify environment profile name (e.g. quiet_room, fan_on, mechanical_keyboard)[/]")
+                    return 1
+                from .audio.noise_profile import AdaptiveNoiseProfiler
+                profiler = AdaptiveNoiseProfiler(sample_rate=app.sample_rate, environment=args.name)
+                profiler.save()
+                console.print(f"[bold green]✔ Switched active noise profile environment to:[/] [bold cyan]{args.name}[/]")
+                return 0
+            elif action == "relearn":
+                console.print("[bold cyan]🔄 Requesting immediate noise profile relearn…[/]")
+                console.print("[dim]Next live or test session will automatically sample ambient silence.[/]")
+                return 0
+        elif cmd in ("settings", "hotkeys"):
+            from .ui.settings_gui import launch_settings_gui
+            launch_settings_gui(app, standalone=True)
+            return 0
+        elif cmd == "help":
+            from .commands.help_cmd import run_help
+            return run_help(args.command)
+        return 0
+    except MicforgeError as exc:
+        console.print(f"[bold red]✖ {exc}[/]")
+        if exc.hint:
+            console.print(f"[yellow]  → {exc.hint}[/]")
+        return 2
+    except KeyboardInterrupt:
+        console.print("\n[dim]bye[/]")
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

micforge/commands/calibrate.py

@@ -0,0 +1,47 @@
+"""`calibrate`: learn the room noise and set the gate threshold."""
+from __future__ import annotations
+
+import time
+
+from rich.progress import BarColumn, Progress, TextColumn
+
+from ..audio.devices import find_device, list_devices
+from ..audio.recorder import Recorder
+from ..config import AppConfig
+from ..dsp.denoise import SpectralDenoiser
+from ..dsp.util import rms_db
+from ..errors import MicforgeError
+from ..profile_store import clear_profile, save_profile
+from ..ui.theme import console
+
+
+def run_calibrate(app: AppConfig, *, seconds: float = 4.0, mic=None, reset: bool = False) -> None:
+    if reset:
+        console.print("[green]Noise profile removed.[/]" if clear_profile(app.sample_rate) else "[dim]No profile saved.[/]")
+        return
+    dev = find_device(mic if mic is not None else app.input_device, "input", list_devices(all_apis=True))
+    console.print(f"[bold]Calibrating[/] on [cyan]{dev.name}[/]. Stay quiet and leave fans/PC running as usual.")
+    rec = Recorder(dev, app.sample_rate, app.input_channel, app.block_size)
+    rec.start()
+    try:
+        with Progress(TextColumn("[yellow]listening…"), BarColumn(), TextColumn("{task.percentage:>3.0f}%"), console=console) as p:
+            task = p.add_task("", total=seconds)
+            while rec.seconds < seconds:
+                p.update(task, completed=min(rec.seconds, seconds))
+                time.sleep(0.05)
+            p.update(task, completed=seconds)
+    finally:
+        noise = rec.stop()
+    if noise.shape[0] < app.sample_rate:
+        raise MicforgeError("Not enough audio captured.")
+    if rec.level.clipping:
+        console.print("[yellow]The mic clipped while calibrating - is something very loud nearby?[/]")
+
+    dn = SpectralDenoiser(app.sample_rate)
+    psd = dn.learn(noise)
+    noise_db = rms_db(noise)
+    gate = noise_db + 9.0
+    save_profile(psd, app.sample_rate, noise_db, gate)
+    console.print(f"[green]✔ Room noise {noise_db:.1f} dBFS.[/] Gate threshold {gate:.1f} dBFS. Profile saved.")
+    if noise_db > -45:
+        console.print("[yellow]That is loud for a room. Try moving the mic closer to your mouth or away from fans.[/]")

micforge/commands/common.py

@@ -0,0 +1,69 @@
+"""Shared plumbing for commands: resolving devices and building a chain with the saved noise profile."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..audio.devices import DeviceInfo, detect_virtual_output, find_device, list_devices
+from ..config import AppConfig
+from ..dsp.chain import Chain, build_chain
+from ..errors import DeviceError
+from ..presets import get_preset
+from ..profile_store import load_profile
+
+
+def make_chain(app: AppConfig, preset: str, model_override: str | None = None) -> tuple[Chain, bool]:
+    """Build a chain for `preset`, applying the saved room-noise profile. Returns (chain, profile_applied)."""
+    cfg = get_preset(preset)
+    prof = load_profile(app.sample_rate)
+    model = model_override or app.denoise_model
+    chain = build_chain(cfg, app.sample_rate, noise_profile=prof[0] if prof else None, model_override=model)
+    applied = False
+    if prof:
+        dn = chain.stage("denoise")
+        applied = bool(dn and getattr(dn, "profile", None) is not None)
+        gate = chain.stage("gate")
+        if applied and gate is not None and cfg.gate.enabled:
+            gate.threshold_db = prof[2]  # type: ignore[attr-defined]
+    return chain, applied
+
+
+@dataclass
+class Devices:
+    mic: DeviceInfo
+    cable: DeviceInfo | None
+    monitor: DeviceInfo | None
+
+
+def resolve_devices(
+    app: AppConfig,
+    *,
+    need_cable: bool,
+    want_monitor: bool,
+    mic_override=None,
+    cable_override=None,
+    monitor_override=None,
+) -> Devices:
+    pool = list_devices(all_apis=True)
+    mic = find_device(mic_override if mic_override is not None else app.input_device, "input", pool)
+
+    cable = None
+    if need_cable:
+        spec = cable_override if cable_override is not None else app.output_device
+        if spec is not None:
+            cable = find_device(spec, "output", pool)
+        else:
+            cable = detect_virtual_output(pool)
+        if cable is None:
+            raise DeviceError(
+                "No virtual audio cable found - Discord needs one to receive the processed mic.",
+                hint="Run `micforge doctor` for install steps (VB-CABLE on Windows, BlackHole on macOS), "
+                "or use `micforge loopback` to just hear yourself.",
+            )
+
+    monitor = None
+    if want_monitor:
+        spec = monitor_override if monitor_override is not None else app.monitor_device
+        monitor = find_device(spec, "output", pool)
+        if cable is not None and monitor.index == cable.index:
+            raise DeviceError("Monitor and virtual cable are the same device - pick your headphones for monitoring.")
+    return Devices(mic, cable, monitor)

micforge/commands/devices_cmd.py

@@ -0,0 +1,86 @@
+"""`devices`, `setup`, `presets`."""
+from __future__ import annotations
+
+import json
+
+from rich import box
+from rich.prompt import Prompt
+from rich.table import Table
+
+from ..audio.devices import DeviceInfo, detect_virtual_output, list_devices
+from ..config import AppConfig
+from ..presets import get_preset, list_presets, user_preset_dir
+from ..ui.theme import console
+
+
+def show_devices(all_apis: bool = False) -> list[DeviceInfo]:
+    devs = list_devices(all_apis)
+    cable = detect_virtual_output(devs)
+    t = Table(box=box.SIMPLE_HEAD, header_style="bold cyan")
+    for c in ("#", "name", "api", "in", "out", ""):
+        t.add_column(c, justify="right" if c in ("#", "in", "out") else "left")
+    for d in devs:
+        tags = []
+        if d.is_default_input:
+            tags.append("default in")
+        if d.is_default_output:
+            tags.append("default out")
+        if cable is not None and d.index == cable.index:
+            tags.append("[green]virtual cable[/]")
+        t.add_row(str(d.index), d.name, d.hostapi, str(d.max_input or ""), str(d.max_output or ""), ", ".join(tags))
+    console.print(t)
+    return devs
+
+
+def _pick(devs: list[DeviceInfo], kind: str, prompt: str, current, allow_skip: bool = False):
+    pool = [d for d in devs if (d.max_input if kind == "input" else d.max_output) > 0]
+    t = Table(box=box.SIMPLE_HEAD, header_style="bold cyan")
+    t.add_column("#", justify="right")
+    t.add_column("name")
+    t.add_column("api")
+    for d in pool:
+        t.add_row(str(d.index), d.name, d.hostapi)
+    console.print(t)
+    valid = {d.index for d in pool}
+    hint = f" (Enter = keep {current!r})" if current not in (None, "") else " (Enter = system default)"
+    while True:
+        raw = Prompt.ask(prompt + hint, default="", show_default=False, console=console).strip()
+        if raw == "":
+            return current
+        if raw.isdigit() and int(raw) in valid:
+            return next(d.name for d in pool if d.index == int(raw))  # store the name: indices change between boots
+        console.print("[red]Not a valid device number.[/]")
+
+
+def run_setup(app: AppConfig) -> None:
+    devs = list_devices()
+    console.rule("[bold cyan]Setup")
+    console.print("[bold]1/3  Your microphone[/]")
+    app.input_device = _pick(devs, "input", "Mic device #", app.input_device)
+    cable = detect_virtual_output(devs)
+    console.print("\n[bold]2/3  Virtual cable output[/] (this is what Discord listens to)")
+    if cable:
+        console.print(f"Detected: [green]{cable.name}[/]")
+    app.output_device = _pick(devs, "output", "Cable device #", app.output_device or (cable.name if cable else None))
+    console.print("\n[bold]3/3  Your headphones[/] (for monitoring and test playback)")
+    app.monitor_device = _pick(devs, "output", "Headphones #", app.monitor_device)
+    app.save()
+    console.print("\n[green]✔ Saved.[/]")
+    console.print(
+        "\n[bold]Now in Discord:[/] Settings → Voice & Video → Input Device = the cable's [bold]recording[/] end "
+        "(Windows: [cyan]CABLE Output[/]). Set Noise Suppression to [bold]None[/], and turn off Automatic Gain Control "
+        "and Echo Cancellation so your voice isn't processed twice."
+    )
+
+
+def show_presets(name: str | None) -> None:
+    if name:
+        console.print_json(json.dumps(get_preset(name).to_dict()))
+        return
+    t = Table(box=box.SIMPLE_HEAD, header_style="bold cyan")
+    t.add_column("preset")
+    t.add_column("description")
+    for p in list_presets():
+        t.add_row(p.name + ("" if p.builtin else " *"), p.description)
+    console.print(t)
+    console.print(f"[dim]`micforge presets NAME` prints a preset as JSON. Drop edited copies into {user_preset_dir()} to use them.[/]")

micforge/commands/diagnostics_cmd.py

@@ -0,0 +1,68 @@
+"""CLI command to export diagnostics and display the plain-English doctor summary."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from rich import box
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from ..config import AppConfig
+from ..diagnostics import collect_diagnostics, export_diagnostics_zip
+from ..ui.theme import console
+
+
+def run_diagnostics_command(
+    app: AppConfig,
+    export_path: str | Path | None = None,
+    export: bool = False,
+) -> int:
+    """Run diagnostics checks, print plain-English summary, and optionally export .zip."""
+    console.print("\n[bold cyan]🔍 Inspecting Micforge system health & audio pipeline…[/]\n")
+
+    report = collect_diagnostics(app)
+
+    # 1. Status Banner
+    status_style = "bold green" if report.overall_status == "HEALTHY" else "bold yellow" if report.overall_status == "WARNING" else "bold red"
+    status_icon = "✔" if report.overall_status == "HEALTHY" else "!" if report.overall_status == "WARNING" else "✖"
+    console.print(Panel(
+        f"[{status_style}]{status_icon} SYSTEM STATUS: {report.overall_status}[/]\n{report.summary_text}",
+        border_style=status_style.split()[-1],
+        box=box.ROUNDED,
+    ))
+
+    # 2. Checks Table
+    t = Table(box=box.SIMPLE_HEAD, header_style="bold cyan", show_lines=False)
+    t.add_column("", width=3)
+    t.add_column("Component", width=22)
+    t.add_column("Assessment")
+
+    for c in report.doctor_checks:
+        st = c["status"]
+        mark = "[bold green]✔[/]" if st == "OK" else "[bold yellow]![/]" if st == "WARN" else "[bold red]✖[/]"
+        t.add_row(mark, c["name"], c["detail"])
+
+    console.print(t)
+
+    # 3. Next Steps / Actionable Advice
+    if report.next_steps:
+        console.print("[bold cyan]Recommended Next Steps:[/]")
+        for step in report.next_steps:
+            console.print(f"  [dim]•[/] {step}")
+        console.print()
+
+    console.print("[dim]📖 For in-depth troubleshooting guides, see:[/] [bold cyan]docs/TROUBLESHOOTING.md[/]\n")
+
+    # 4. Optional Export
+    if export or export_path:
+        out = export_diagnostics_zip(report, Path(export_path) if export_path else None)
+        console.print(Panel(
+            f"[bold green]✔ Diagnostics exported successfully![/]\n[white]{out}[/]\n[dim]All passwords, API tokens, and home directory paths have been securely redacted.[/]",
+            border_style="green",
+            box=box.ROUNDED,
+        ))
+
+    return 0 if report.overall_status != "CRITICAL" else 1
+