Why won't this project run on my machine?

PreBoot diagnoses local setup failures. Define your project's environment requirements in YAML, run one command, and get a clear pass/fail report with actionable fixes.

Installation

Prebuilt binaries — download the archive for your platform from the latest release, extract it, and place preboot on your PATH.

With Go (1.25+):

go install github.com/allenbiji/preboot/cmd/preboot@latest

Verify the install:

preboot --version

Quick Start

# 1. Auto-generate checks from your project
preboot init

# 2. Run diagnostics
preboot check

# 3. (Optional) Validate your config without running checks
preboot validate

PreBoot auto-detects go.mod, Makefile, docker-compose.yml, and .env.example files to generate a baseline preboot-auto.yml. Add your own checks in preboot.yml.

---

How It Works

Checks are defined in YAML and grouped by severity:

version: 1

checks:
  - name: go-installed
    type: command_exists
    severity: blocker
    options:
      command: go
    fix: "Install Go from https://go.dev/dl/"

  - name: env-file-exists
    type: file_exists
    severity: blocker
    options:
      path: .env
    fix: "Run: cp .env.example .env"

  - name: postgres-reachable
    type: tcp_reachable
    severity: blocker
    options:
      address: "localhost:5432"
    fix: "Start Postgres: docker compose up db -d"

Seven built-in check types:

Type	What it checks
command_exists	Command available in $PATH
file_exists	File present at relative path
directory_exists	Directory present at relative path
env_exists	Key set in .env file
http_reachable	HTTP endpoint returns 2xx
tcp_reachable	TCP connection succeeds
port_free	Port is not already in use

Three severity levels:

Severity	Behaviour
blocker	Fails the run (exit code 1)
warning	Fails the run when strict: true (default)
info	Always informational; never fails the run

Exit codes: 0 all clear · 1 check failures · 2 config/internal error

---

Commands

Command	Description
preboot init	Auto-generate preboot-auto.yml from your project
preboot init --force	Overwrite an existing preboot-auto.yml
preboot check	Run all checks
preboot check --config FILE	Run checks from a specific file
preboot check --quick	Skip network checks (http_reachable, tcp_reachable)
preboot validate	Validate config YAML without running checks

---

Config Files

PreBoot merges two optional files from your working directory:

• preboot-auto.yml — Generated by preboot init. Commit this.
• preboot.yml — Your custom checks and overrides. Commit this too.

A check in preboot.yml with the same name as one in preboot-auto.yml overrides it. Use this to tighten auto-detected checks or add project-specific ones.

---

Documentation

• Getting Started — Installation, first run, environment controls
• Configuration Reference — Full YAML schema and merging rules
• Check Types Reference — All 7 types with options and examples
• CLI Commands Reference — Commands, flags, and exit codes
• Architecture — Package map, data flow, extension points
• Contributing — Dev setup, adding check types, conventions
• Testing Guide — Test patterns and coverage rules
• Manual Test Plan — Pre-release install and functional QA matrix

---

Development

make build   # build ./preboot
make test    # run tests with race detector
make ci      # build + vet + test (mirrors CI)
make help    # list all targets