Botstrap

Cross-platform bootstrap for developers and AI coding agents: one entry point on macOS, Linux, and Windows to install prerequisite CLI tooling, pick core and optional tools in a gum TUI (core defaults to all selected), then apply configs and verify installs — with predictable PATH, non-interactive CLIs by default, and configs/ scaffolding suited to agents.

Quick start (from a published clone)

# macOS / Linux (default BOTSTRAP_REPO is https://github.com/an-lee/botstrap.git; override to use a fork)
curl -fsSL https://botstrap.dev/install | bash

# Windows (PowerShell); default clone URL matches boot.sh — set $env:BOTSTRAP_REPO to use a fork
irm https://botstrap.dev/install.ps1 | iex

Elevated PowerShell ("Run as Administrator") is optional but recommended so Phase 0b can apply Developer Mode and long paths automatically; without it, the install still runs and those steps are skipped with a warning.

For local development, run the orchestrator from this repository:

macOS / Linux

export BOTSTRAP_ROOT="$(pwd)"
./install.sh

Windows (PowerShell)

$env:BOTSTRAP_ROOT = (Get-Location).Path
.\install.ps1

Layout

• boot.sh / boot.ps1 — clone ~/.botstrap and start install.*
• install.sh / install.ps1 — phases 0, 0b (Windows), 2–4
• lib/ — detect, log, pkg (registry-driven installs on Unix)
• registry/prerequisites.yaml — Phase 0 tools (git, curl, jq, yq, gum)
• registry/core.yaml — TUI multi-select core stack (installed after confirm)
• registry/optional.yaml — TUI selections (editor, languages, databases, AI CLIs, themes, apps)
• configs/ — shell, git, editor, and agent templates
• docs/ — architecture, registry spec, contributing

CLI (this checkout)

After Phase 3 on macOS/Linux, open a new shell (or source ~/.zshrc / ~/.bashrc): botstrap is on your PATH via ~/.config/botstrap/env.sh. Until then, or on Windows without that hook, use the script path:

./bin/botstrap             # interactive menu (TTY + gum); scripts should use explicit subcommands below
./bin/botstrap version
./bin/botstrap update      # git pull in repo root
./bin/botstrap reconfigure # TUI + configure phases
./bin/botstrap doctor      # install status + prerequisite and selected-core verify (exits 1 if any verify fails)
./bin/botstrap uninstall   # remove shell hooks; optional --purge / --remove-checkout (see docs/REFERENCE.md)

Documentation

• Site: botstrap.dev — browsable docs (VitePress)
• Introduction — what Botstrap does, end to end
• Getting started — install, local dev, non-interactive runs
• After install — installed stack and how to use it
• Defaults & customization — default config and how to change it
• Reference — CLI, environment variables, artifacts
• Configuration file map — configs/ templates and where they land
• Architecture
• Registry specification
• Tool selection
• Cross-platform notes
• AI agent friendliness — including automated doc maintenance via the daily-doc-updater workflow
• Contributing

Deployment (Cloudflare Pages)

Production docs and install scripts are served from https://botstrap.dev via Cloudflare Pages.

Setting	Value
Build command	npm ci && npm run docs:build
Build output directory	docs/.vitepress/dist
Node.js version	22

Connect this repository in the Cloudflare dashboard (Workers & Pages → Create → Pages), then attach the custom domain botstrap.dev. Boot scripts are copied into the static output as /install and /install.ps1 on each build (see scripts/sync-install-assets.mjs).

Manual deploy after a local build:

npm run docs:build
npx wrangler pages deploy

With wrangler.toml at the repo root, Wrangler uses pages_build_output_dir and project name; override with npx wrangler pages deploy docs/.vitepress/dist --project-name=botstrap if needed.

Version

See the version file (semver reported by ./bin/botstrap version and Phase 4 summary).