Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
178 changes: 105 additions & 73 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,125 +1,157 @@
<img width="3840" height="1000" alt="Boo - Banner (1)" src="https://github.com/user-attachments/assets/4e8ae86b-c671-4aa5-9f34-9cabb59d1fe1" />

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
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/<name>.theme`:
You can also create `~/.config/boo/themes/<name>.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 <name>
```

Then run `boo theme <name>`.

### Prompt (how your shell prompt looks)
Choose between Boo's built-in prompt and oh-my-posh.
### Prompt backend

```bash
boo prompt
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
Expand All @@ -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

Expand Down
Loading