Bootwitch CLI Scaffold
A safety-minded project scaffolder built with Codex, with shell templates and a recorded CLI demonstration.
A little structure. A little shell magic. A more consistent place to start.
Jennifer Naomi Nguyen · Built with Codex · Current release: v0.3.0
What I built
View source on GitHub · v0.3.0 release
Bootwitch is my project starter for small scripting projects. It puts folders, scripts, tests, and documentation in place so there's a clear starting point for the work that comes next.
It began with a very small annoyance: I wanted to save the ten seconds it took to copy a project template, so naturally I spent considerably longer automating it. That turned into a place to learn how paths, wrappers, permissions, tests, and documentation fit together.
It also became the first place my development workflow took a recognizable shape: describe the problem and the behavior I want, build it with ChatGPT and Codex, then follow the failures until the connections make sense. I did not yet have the vocabulary for a CLI or an orchestrator. I was building the thing first and learning what to call it afterward.
Bootwitch runs locally on macOS and Linux. It does not need the portfolio's Worker, a hosted service, or a cloud account to create and run projects.
You can create a project with a single command or use summon for a guided setup. The shell template includes friendly wrappers for common tasks, including a little hello to help you find your footing.
The witchy names are part of the fun. Underneath them, the job is practical: make setup repeatable and keep the pieces understandable as a project grows.
See it working
Watch the 46-second demo · Read the guided walkthrough transcript · Try the walkthrough
The demo follows a real local run: create a project, add a script, see its documentation appear, then run the workflow and tests. The video is silent, with captions and edited pacing.
Guided spellbook walkthrough
Watch the 97-second walkthrough
This captioned replay uses real command output from Bootwitch help, environment
inspection, project discovery, and the guided summon flow. It is silent and
tightens the pauses between steps.
The part I like most
A new script gets a header describing what it does, what it takes in, and what it produces. Bootwitch reads those comments and adds the script to the project's README reference.
That keeps useful information close to the thing it describes. The introduction and other human-written notes stay outside the generated section, so there's still room to explain a project in your own words.
If creating the script works but refreshing the README doesn't, Bootwitch keeps the script and gives you a command to retry the documentation step. Small details like that make the workflow easier to pick back up.
How the pieces fit
| Piece | What it's for |
|---|---|
| Base template | The shared starting structure and project information |
| Shell template | Scripts, reusable modules, wrappers, and tests for Bash projects |
| Guided setup | A conversational way through the same setup as the direct command |
| Script generator | A starting script with its own annotated header |
| README builder | A readable reference assembled from the project's metadata and comments |
How v0.2.1 works
A central CLI handles environment checks, template discovery, and project creation, while each generated project keeps its own versioned script template. Adaptive discovery locates the nearest Bootwitch project and selects the right documentation workflow without executing project source. Source annotations generate both a readable component overview and a function-level technical reference.
Safety is built into the workflow. Existing files are not silently replaced, machine-specific paths are avoided, and documentation failures are reported as recoverable partial successes rather than hiding work that did finish.
The repository covers CLI behavior, scaffolding, overwrite protection, documentation separation, release safety, and ShellCheck setup with regression tests. The central engineering lesson was that working components are not enough: the connections between entry points, state transitions, and outputs have to be tested and observable too.
What it taught me
Bootwitch taught me why relative paths mysteriously stop working when a folder moves, that you can make a wrapper for basically anything, and that Bash takes typos personally. It also confirmed that I will spend an unreasonable amount of time automating a tiny repeated task. The upside is that I see systems everywhere.
I built Bootwitch with Codex. The interesting decisions were about where configuration belongs, how a script finds its own project, and how the tool refuses to publish a partial or overwritten one — and those are the parts worth asking me about.
The current release focuses on base and shell projects; setup instructions and tests are in the repository.
Elsewhere in the portfolio
Bootwitch Portfolio: UI Evolution tells the story of the website interface. Bootwitch Lab is my private AI workspace. This page is about the CLI you run locally.