README
¶
PreBoot
"Why doesn't it work 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 bypreboot 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
Directories