# Host terminal themes (Bare OS–maintained)

These files mirror common terminal emulator formats so you can match your **host** terminal (outside Bare OS) to the same named presets used inside the session (`theme set <name>`).

**If colors look wrong in the guest:** see [users-manual — Troubleshooting](../../users-manual/07-troubleshooting-and-operations.md#themes-and-terminals) and [docs/troubleshooting.md](../troubleshooting.md).

They are **authored in-repo** for consistency with [`bare-os-theme-presets.js`](../../packages/bare-os-booter/lib/bare-os-theme-presets.js). They are **not** downloaded from third-party theme galleries.

Naming follows common patterns (similar in spirit to catalogs like [terminalcolors.com](https://terminalcolors.com/)): `alacritty-<preset>.yml`, `warp-<preset>.yaml`, `iterm-<preset>.itermcolors`.

---

## On this page

- [Bundled theme files](#bundled-theme-files)
- [Preset names](#preset-names)
- [Related session variables](#related-session-variables)

---

## Bundled theme files

- **`alacritty-nord.yml`** — Preset **`nord`**. [Alacritty](https://github.com/alacritty/alacritty) YAML. **Import:** merge the `colors:` block into your `alacritty.yml`.
- **`alacritty-dracula.yml`** — Preset **`dracula`**. Alacritty YAML. **Import:** same as above.
- **`warp-nord.yaml`** — Preset **`nord`**. [Warp](https://docs.warp.dev/appearance/custom-themes) theme. **Import:** use Warp’s theme picker or point it at this path.
- **`warp-dracula.yaml`** — Preset **`dracula`**. Warp. **Import:** same as above.
- **`iterm-nord.itermcolors`** — Preset **`nord`**. iTerm2 / Terminal.app. **Import:** **Profiles → Colors → Color Presets → Import**.
- **`iterm-dracula.itermcolors`** — Preset **`dracula`**. iTerm2 / Terminal.app. **Import:** same as above.

Additional presets (`gruvbox_dark`, `tokyo_night`, `catppuccin_mocha`, …) can be added here using the same filenames; contributions should keep parity with the JavaScript preset names in the booter.

---

## Preset names

Run `theme list` in a Bare OS shell. Examples: `default`, `nord`, `dracula`, `gruvbox_dark`, `catppuccin_mocha`, `tokyo_night`, `github_dark`, `solarized_dark`.

---

## Related session variables

See [environment variables reference](../reference/environment-and-posix-appendix.md#14-environment-variables-complete-list): `BARE_OS_THEME`, `BARE_OS_COLOR_DEPTH`, `LS_COLORS`, `BARE_OS_DIRCOLORS`, and host passthrough `TERM` / `COLORTERM`.

---

## Matching host and guest colors

Bare OS computes **`LS_COLORS`** from **`dircolors`** data and the active theme preset (**`bare-os-theme-presets.js`**). If the **guest** looks correct but your **host** terminal looks washed out, import the matching file from this directory (Alacritty, Warp, or iTerm). If the **guest** looks wrong, set **`BARE_OS_COLOR_DEPTH`** to **`256`** or **`truecolor`** to match what your emulator advertises via **`COLORTERM`**, then run `**theme set <name>`** inside the session. See [Handbook — Chapter 7: Themes, LS_COLORS, and real terminals](../../handbook/07-operations-and-development.md#themes-ls_colors-and-real-terminals).

---

## Contributing a new preset

1. Add the preset object to [`packages/bare-os-booter/lib/bare-os-theme-presets.js`](../../packages/bare-os-booter/lib/bare-os-theme-presets.js) (colors for **`LS_COLORS`** / **`dircolors`** generation).
2. Add host theme files here using the existing naming convention (`alacritty-<preset>.yml`, `warp-<preset>.yaml`, `iterm-<preset>.itermcolors`).
3. Document the preset name in this README under **Preset names** so operators can discover it.