From b09d2936c366d3c628fe7b64313445b81f40fcb3 Mon Sep 17 00:00:00 2001 From: ansub Date: Wed, 25 Feb 2026 22:40:41 +0530 Subject: [PATCH] docs: make README beginner-first with quickstart and troubleshooting --- README.md | 178 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 105 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 175ee2c..7a4fcc5 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,45 @@ Boo - Banner (1) -Boo helps you make your terminal look and feel better in minutes — without manually editing config files. +# Boo -## What You Get - -- Beautiful ready-to-use themes (plus easy custom theme creation) -- Better defaults for Ghostty + Zsh setup -- A clean startup panel and optional splash art -- Simple commands to change opacity, theme, prompt, and mode -- Create your own theme in seconds with `boo theme create` -- Quick troubleshooting with `boo doctor` -- Safe install/upgrade/uninstall flow with backups +Boo helps you make Ghostty + Zsh look good in minutes without hand-editing config files. -## Great for beginners +## Start Here (2 to 5 minutes) -If you're new to terminal setup, Boo gives you a polished setup fast with one command and easy controls: +Copy and run these commands in order: ```bash +curl -fsSL https://boo.ansub.co/install.sh | bash +source ~/.zshrc +boo doctor boo theme fallout boo opacity glass ``` +Expected result: + +- `boo doctor` runs checks and tells you if anything needs fixing. +- `boo theme fallout` changes your color theme. +- `boo opacity glass` updates background transparency. + +If theme or opacity does not change right away, jump to [If Something Looks Wrong](#if-something-looks-wrong). + +## What You Get + +- Ready-to-use themes and easy custom theme creation +- Better Ghostty + Zsh defaults +- Startup panel plus optional splash art +- Simple commands for theme, opacity, prompt, and mode +- Built-in troubleshooting with `boo doctor` +- Safe install/upgrade/uninstall flow with backups + +## Prerequisites + +- macOS (tested) +- [Ghostty](https://ghostty.org/) +- `zsh` +- [oh-my-posh](https://ohmyposh.dev/) (optional, only needed for `boo prompt set omp`) + ## Install ```bash @@ -28,81 +47,96 @@ curl -fsSL https://boo.ansub.co/install.sh | bash source ~/.zshrc ``` -Open a new Ghostty window, then run: +Safety notes: + +- Installer creates timestamped backups before replacing files. +- `boo uninstall` can restore your previous Ghostty config when a backup exists. + +## Verify It Worked ```bash boo doctor +boo status +``` + +Expected result: + +- `boo doctor` shows mostly successful checks, or tells you exactly what to run next. +- `boo status` shows your current theme, mode, splash, prompt, and opacity. + +## First Customization (3 commands) + +```bash boo theme fallout +boo opacity glass +boo prompt set native ``` -## If changes don't apply immediately +Optional preview: -- Press `Cmd+Shift+,` in Ghostty, or -- Run `boo reload --unsafe` +```bash +boo preview all +``` -## Requirements +## If Something Looks Wrong -- macOS (tested) -- [Ghostty](https://ghostty.org/) -- `zsh` -- [oh-my-posh](https://ohmyposh.dev/) (optional) +### `boo: command not found` -## First 5 Minutes +```bash +source ~/.zshrc +``` + +Then open a new Ghostty window and run: ```bash boo doctor -boo status -boo theme fallout -boo opacity glass -boo reload --unsafe ``` -## Common Commands +### Theme or opacity did not apply + +- Press `Cmd+Shift+,` in Ghostty. +- Or run `boo reload --unsafe`. +- If opacity still does not change on macOS, fully restart Ghostty. -### Themes (change your terminal colors) -Switch themes, preview them, and manage your custom themes. +### `boo doctor` reports issues + +```bash +boo doctor fix +boo doctor +``` + +## Common Tasks + +### Themes ```bash boo theme list boo theme abyss -boo crimson # shorthand +boo crimson boo preview all boo preview abyss --plain ``` -### Create themes (make your own look) -Generate a new theme from an accent color, or create one manually. +### Create your own theme ```bash -# Direct mode (one command) +# One command boo theme create --name synthwave --accent '#ff3ea5' -# Iterative mode (guided prompts) +# Guided prompts boo theme create +# Delete a custom theme boo theme delete synthwave ``` -You can also create a theme file directly in `~/.config/boo/themes/.theme`: +You can also create `~/.config/boo/themes/.theme` manually, then run: -```ini -description=my custom theme -accent=#ff6a00 -bg=#0a0400 -fg=#ffb870 -cursor=#ff6a00 -cursor_text=#000000 -selection_bg=#2a1800 -selection_fg=#ffd4a0 -pal_0=#0a0400 -... -pal_15=#ffe8cc +```bash +boo theme ``` -Then run `boo theme `. - -### Prompt (how your shell prompt looks) -Choose between Boo's built-in prompt and oh-my-posh. +### Prompt backend ```bash boo prompt @@ -110,16 +144,14 @@ boo prompt set native boo prompt set omp ``` -### Mode (what info is shown on startup) -Control how much detail Boo shows when terminal opens. +### Startup mode ```bash boo mode full boo mode public ``` -### Splash art (startup visual) -Pick the startup art, use your own, or disable it. +### Splash art ```bash boo splash list @@ -129,50 +161,50 @@ boo splash none boo splash reset ``` -### Reload + doctor (apply and troubleshoot) -Reload terminal config and run health checks when something feels off. +### Health + reload ```bash -boo reload -boo reload --unsafe boo doctor boo doctor fix +boo reload +boo reload --unsafe ``` -### Uninstall (remove Boo cleanly) +## Uninstall / Restore ```bash boo uninstall -# or non-interactive +# non-interactive boo uninstall --yes ``` +Expected result: + +- Boo-managed setup is removed. +- Previous Ghostty config is restored when available. + ## Theme Intent - `abyss`: deep indigo with violet-magenta accents (default) - `clay`: warm cream light mode with earthy terracotta accents - `crimson`: high-contrast red mode -- `fallout`: RobCo phosphor CRT — warm amber-lime on near-black +- `fallout`: RobCo phosphor CRT, warm amber-lime on near-black - `lunar`: desaturated monochrome noir -- `moss`: damp forest floor — muted earthy green -- `rust`: oxidized metal — brutalist copper - -## Roadmap +- `moss`: damp forest floor, muted earthy green +- `rust`: oxidized metal, brutalist copper -- Font controls (`boo font`) are planned and will return in an upcoming release. -- More quality-of-life improvements for first-time setup. -## Reload Behavior +## Advanced Notes - `boo reload`: safe guidance only (no key injection, no window/session changes) -- `boo reload --unsafe`: tries to trigger Ghostty `reload_config` via detected comma-based keybind (`Cmd+Shift+,` or `Cmd+,`) +- `boo reload --unsafe`: tries to trigger Ghostty `reload_config` via comma-based keybind (`Cmd+Shift+,` or `Cmd+,`) - Theme changes auto-run safe reload - Opacity changes auto-run unsafe reload - On macOS, `background-opacity` can still require a full Ghostty restart -## Notes +## Roadmap -- Installer creates timestamped backups when replacing files. -- `boo uninstall` restores your original Ghostty config when available, otherwise removes Boo-managed config. +- Font controls (`boo font`) are planned and will return in an upcoming release. +- More quality-of-life improvements for first-time setup. ## License