Diagnose & repair with Doctor

createrun-doctor is the instance diagnostic CLI. Start with a read-only check, inspect the evidence for a finding, and preview a targeted repair before changing anything.

Check firstEvidence per findingWindows / Linux / macOS source

Find Doctor in the instance

Use the actual install root, the directory containing Services/ and Web/. Check that the platform's binary exists before running a command. A missing binary is an availability problem; it is not a healthy diagnostic result.

PlatformExpected path inside the install root
WindowsServices\Application Service\Doctor\createrun-doctor.exe
LinuxServices/Application Service/Doctor/createrun-doctor (ELF)
macOSServices/Application Service/Doctor/createrun-doctor (shell launcher, if separately supplied)
macOS distribution is pending. Doctor's Mac source exists, but the current release path cannot ship its launcher into an instance. Do not expect it in a normal macOS install yet. The Mac commands below apply only after a matching Doctor build has been supplied and verified separately.

1. Check, then explain a finding

check changes nothing. Supply --instance so Doctor cannot select another installation. Use --verbose to see the control evidence. The examples use LAY-001 as a Tier 1 example ID; replace it with a finding from your own check.

Linux or macOS

INSTANCE_ROOT="/opt/createrun"
DOCTOR="$INSTANCE_ROOT/Services/Application Service/Doctor/createrun-doctor"
test -x "$DOCTOR" && sudo "$DOCTOR" check --instance "$INSTANCE_ROOT" --verbose
sudo "$DOCTOR" explain LAY-001

Windows PowerShell

$instanceRoot = 'C:\Createrun'
$doctor = "$instanceRoot\Services\Application Service\Doctor\createrun-doctor.exe"
if (Test-Path -LiteralPath $doctor) { & $doctor check --instance $instanceRoot --verbose }
& $doctor explain LAY-001

On a Mac, a non-root run can see only part of the port and open-file inventory. Use sudo for a full check when a Mac Doctor build becomes available.

2. Read the result before acting

  • Find the positive and negative control result. If the report says the measurement is invalid, do not interpret its findings as instance health.
  • INCONC means the check could not decide. SKIP means it did not run. Neither means “passed.” --skip-network deliberately skips network checks.
  • Exit 0 means no finding reached the configured --fail-on threshold. Warnings may still exist. Exit 1 means usage or instance resolution failed; exit 2 means findings remain or the measurement was invalid.
  • For services status --out json, process exit 0 and lockProbe.safeToWrite answer different questions. A file-copy workflow must inspect safeToWrite; Linux can report its lock probe as measured:false.

3. Preview a targeted repair

Use --only with a finding you have explained. First run fix --dry-run, read its affected files, backup and undo command, then choose the tier and run the repair. Run check again to verify the finding.

Linux or macOS (when Doctor is present)

INSTANCE_ROOT="/opt/createrun"
DOCTOR="$INSTANCE_ROOT/Services/Application Service/Doctor/createrun-doctor"
sudo "$DOCTOR" fix --instance "$INSTANCE_ROOT" --only LAY-001 --tier 1 --dry-run

Windows PowerShell

$instanceRoot = 'C:\Createrun'
$doctor = "$instanceRoot\Services\Application Service\Doctor\createrun-doctor.exe"
& $doctor fix --instance $instanceRoot --only LAY-001 --tier 1 --dry-run

After reviewing the preview, remove --dry-run from the same targeted command to apply the repair. Then run check --instance <install-root> --only LAY-001 using that platform's Doctor path. For a Tier 2 finding, use --tier 2 only after reading its consent block.

fix changes state. Tier 1 repairs are reversible but can run without a prompt. A failed repair pass may also enable a temporary Debug logging overlay. Tier 2 can change services, files or version state and requires its separate consent. Use your platform's verified Doctor path in place of createrun-doctor above.

undo --last reverses the latest Doctor repair transaction when needed. It does not restore an uninstalled instance or a database.

Other useful commands

CommandPurpose and limit
services status --instance <root> --out jsonReads owned service state and lock-probe evidence. services stop/start/restart changes state; put the action immediately after services.
snapshot --instance <root>Writes a SHA-256 file-integrity baseline after a known-good install or update. It is not a database or application-data backup.
report --instance <root> --bundle <path>Writes a support bundle with mandatory redaction. Review the bundle before sharing it.
undo --lastReverts the last Doctor repair transaction. rollback framework is a separate version operation; rollback app is not implemented and returns exit 2.

Platform and evidence status

Doctor availability depends on the release actually installed on your machine. The command surface above is based on current source and help text. Check the installed binary's --version and --help before relying on a newer command. The macOS implementation has not been run on a real Mac, and its release packaging remains open.