# Create a custom theme with the Fifteen CLI

Fifteen ships with the `fifteen` CLI, which includes a `theme` subcommand for
managing custom themes. Themes are plain JSON files stored in the Fifteen data
directory (typically `~/.fifteen/themes/`).

## Prerequisites

- Fifteen installed (see [install.md](./install.md)). The installer places a
  symlink at `/usr/local/bin/fifteen`.

## The `theme` subcommands

```
fifteen theme new <NAME>     Create a new theme file with default values
fifteen theme example         Print the Catppuccin theme as example JSON
fifteen theme schema          Print the JSON schema for the theme format
fifteen theme list            List built-in presets and custom themes
fifteen theme switch <NAME>   Switch the active theme
```

## Create a theme

1. **Scaffold the file.**

   ```sh
   fifteen theme new my-theme
   ```

   This writes `~/.fifteen/themes/my-theme.json` pre-filled with a dark
   template. The command refuses to overwrite an existing file.

2. **Edit the JSON.** The template exposes grouped colour tokens:
   `background`, `accent`, `telegram`, `bubble`, `status`, and more. Each value
   is a hex string (`#rrggbb` or `#rrggbbaa`). To see every field, print the
   schema:

   ```sh
   fifteen theme schema
   ```

   Or crib from a real preset:

   ```sh
   fifteen theme example > ~/.fifteen/themes/my-theme.json
   ```

   Top-level `"mode"` must be `"dark"` or `"light"` — it controls which system
   affordances Fifteen adjusts alongside your palette.

3. **Activate it.**

   ```sh
   fifteen theme switch my-theme
   ```

   The file extension is optional; `my-theme` and `my-theme.json` both work.
   Built-in preset names (`dark`, `light`, `catppuccin`, `monokai`,
   `night-owl`) are also valid arguments.

4. **Verify.** List themes to confirm it registered:

   ```sh
   fifteen theme list
   ```

   Output looks like:

   ```
   Built-in presets:
     Dark — Default dark theme
     Light — Clean light theme
     Catppuccin — Soothing pastel colors
     Monokai — Classic Sublime Text theme
     Night Owl — Optimized for low-light

   Custom themes (/Users/you/.fifteen/themes):
     my-theme
   ```

## Tips

- Fifteen picks up theme changes immediately — no restart needed.
- To revert, `fifteen theme switch dark` (or any other preset).
- Delete the JSON file to remove a custom theme; if it was active, switch to a
  preset first.
- Invalid JSON or unknown keys will cause Fifteen to fall back to the default
  theme, so validate with `fifteen theme schema` if colours look wrong.