kicad

Usage

kicad-cruncher kicad installs
kicad-cruncher kicad running
kicad-cruncher kicad launch --version 10.0 --app kicad --new
kicad-cruncher kicad launch --version 10.99 --app pcbnew --project board.kicad_pcb --dry-run
kicad-cruncher kicad stop --all
kicad-cruncher kicad prefs
kicad-cruncher kicad prefs --version 10.0 --open config
kicad-cruncher kicad prefs --version 10.0 --open documents
kcr kicad installs

Arguments

installs lists detected KiCad install roots, command paths, reported versions, and whether the version looks like a nightly/dev build such as 9.99 or 10.99. running lists active KiCad-family processes. launch starts one detected or explicit KiCad executable with --app kicad, --app pcbnew, --app eeschema, or --app kicad-cli. --project passes a file argument to the selected executable; for kicad.exe, KiCad source accepts project-manager inputs as .kicad_pro or legacy project files. --new passes KiCad's project-manager new-instance switch so a no-project launch does not reload the last open project. stop terminates matching running KiCad processes only when --all is supplied; without --all it prints the processes that would be stopped. --version and --app narrow the stop set before --all is applied. prefs lists config and document roots for each discovered version and can open one path in the platform file explorer. A short kcr console alias should route to the same CLI entry point while kicad-cruncher remains the canonical executable.

Output

The command defaults to readable text for workstation use and supports --json on every subcommand for automation and installer reuse. Versioned records include the KiCad version folder, install root, executable paths, config path, document plugin path, IPC API preference state when readable, configured Python interpreter, and detected running process IDs. The command tolerates multiple KiCad installations on one machine, including stable and nightly .99 installs, and requires explicit --version selection before launch when more than one matching executable is discovered.

Install Integration

The plugin installer can reuse these helpers before editing KiCad preferences. If KiCad is running and plugin install --enable-api is requested, the installer should fail with a clear message unless --best-effort is present. With --best-effort, it may install plugin files, skip preference edits, and tell the user to close KiCad and rerun setup. Any future installer-triggered stop flow must call the same kicad stop helper and keep process termination opt-in.

Platform Policy

Discovery stays dependency-light and platform-native. Windows discovery inspects common Program Files and LocalAppData KiCad roots plus KICAD_EXE, KICAD_CLI, KICAD_INSTALL_ROOT, KICAD_HOME, and KICAD_PATH. POSIX and macOS discovery honor the same environment overrides and standard application/config locations where practical. File-explorer opening uses explorer on Windows, open on macOS, and xdg-open on Linux.

Ownership

kicad_cruncher owns this command because it is workflow and installation orchestration. kicad_monkey remains the owner of KiCad file parsing, model helpers, and rendering primitives. The helper command may compose with kicad_monkey in future validation commands, but process management, preference directory discovery, plugin install safety, and launch/stop UX belong in kicad_cruncher.

Tests

L0 covers parser registration, help text, JSON output shape, environment-overridden install discovery, version-folder discovery including 10.99, preference path reporting, process parser behavior with mocked subprocess output, dry-run stop behavior, --all stop confirmation through a mocked terminator, launch command construction without starting real KiCad, --new command construction for the project manager, and both kicad-cruncher and kcr console script entry points. Live process detection and actual launch/stop behavior are optional workstation validation until stable cross-platform runners exist.