CLI themes

The formae CLI is themeable. A theme controls the colors, glyphs, spinner, progress bar, and a few behavioral touches used across every interactive screen (the apply/destroy preview, the live status view, and formae inventory). Themes ship as TOML files: formae has built-in themes compiled into the binary, and you can drop your own into a directory to add or override one.

Selecting a theme

Set cli.theme in your profile (see Configuration):

cli {
    theme = "rich"
}

The value is the name of a built-in theme, or the filename (without .toml) of a theme in ~/.config/formae/themes/. An unknown name prints a warning that lists every available theme (the built-ins plus any of your own in ~/.config/formae/themes/) and falls back to quiet.

Available themes

formae ships with the following themes:

Theme	Description
`quiet` (default)	Restrained. Operations render in a single neutral color — the glyph and the word (for example `+ create`) carry the meaning, not the color. Best when you want a calm, low-color terminal.
`rich`	Per-operation colors: create is green, update is blue, delete is olive, replace is orange. Resource labels are accent-colored, the pre-execution confirmation bar is colored by severity, and the logo wordmark is blue.
`colorblind`	A colorblind-safe palette built around a blue/orange pairing rather than red-versus-green, so operation and status states stay distinguishable without relying on those hues.
`nord`	Nord: arctic blues on a cool, dark base.
`gruvbox`	Gruvbox: warm, retro earth tones.
`tokyo-night`	Tokyo Night: deep blue night with neon accents.
`rose-pine`	Rosé Pine: muted rose and pine on a soho base.
`catppuccin-latte`	Catppuccin Latte: soft pastels on a light background.
`omarchy`	Derives its palette live from your active Omarchy desktop theme and follows OS theme switches. See Omarchy below.

The nord, gruvbox, tokyo-night, rose-pine, and catppuccin-latte themes reuse quiet’s restrained behavior and change only the palette, so glyphs and layout stay neutral while each operation is tinted from the scheme.

theme = "formae" is accepted as an alias for quiet so existing configurations keep working.

Every theme is self-contained, so you can extends any of them from your own theme (see Inheritance) to start from its palette and change glyphs or behavior.

The palettes of the color-scheme themes are derived from the corresponding Omarchy themes and, in turn, the upstream color schemes: Nord, Gruvbox, Tokyo Night, Rosé Pine, and Catppuccin. All credit for the color work belongs to their authors.

Light and dark appearance

Every theme color has both a light and a dark variant. cli.appearance chooses which side is used, independently of the theme:

cli {
    theme = "rich"
    appearance = "auto"   // "light" | "dark" | "auto"
}

auto (default) detects the terminal background.
light / dark force the corresponding variant. Use this when auto-detection is unreliable — for example inside tmux, over SSH, or in a terminal that does not report its background color.

The appearance is resolved with the following precedence, highest first:

The FORMAE_APPEARANCE environment variable (light or dark) — a one-off override that beats the config.
cli.appearance in the profile, when it is not auto.
Auto-detection of the terminal background.

FORMAE_APPEARANCE=light formae inventory

Omarchy

On an Omarchy desktop, cli.theme = "omarchy" makes the CLI follow your active desktop theme instead of using a fixed palette.

cli {
    theme = "omarchy"
    appearance = "auto"
}

Where the colors come from. formae reads your active Omarchy theme’s colors.toml (at ~/.config/omarchy/current/theme/colors.toml) and maps its values onto formae’s semantic palette — accent becomes the primary accent and the logo wordmark, the 16 ANSI colors (color0–color15) fill the per-operation and state colors, background/foreground set surfaces and text, and so on. Sparse themes fall back per key, so every color slot stays populated. If no Omarchy theme is present (or its colors.toml can’t be read), formae warns once and falls back to the quiet theme. Light and dark. With appearance = "auto", an Omarchy theme’s own light/dark declaration is preferred over terminal auto-detection, so a light Omarchy theme renders formae’s light variant and a dark one its dark variant. Setting appearance to light or dark explicitly still overrides this. Live-follow. Switching your desktop theme while a long-running view is open — formae inventory or the status watch — recolors it in place, without restarting the command. formae watches the Omarchy current/theme symlink and re-resolves the theme when your desktop swaps it (the atomic switch that omarchy-theme-set performs), as well as an in-place edit to colors.toml. One-shot commands aren’t watched; they pick up the current theme each time they run.

Authoring a theme

A custom theme is a TOML file in ~/.config/formae/themes/. The filename is the theme name: ~/.config/formae/themes/midnight.toml is selected with cli.theme = "midnight". A theme in that directory whose name matches a built-in shadows the built-in. The quickest way to start is to copy a built-in theme’s structure and change what you need. A theme has a set of appearance planes ([palette], [glyphs], [progress], [spinner]) and a few behavior toggles ([confirmation_bar], [header], [rows]).

Colors

Every [palette] value is either a single hex string used for both appearances, or a table with explicit light and dark variants:

[palette]
text_primary   = { light = "#1A1A1A", dark = "#E8E8E8" }
warning        = "#B5B55B"   # same in both appearances

cli.appearance selects which side of the two-variant colors is used at render time.

Inheritance

A theme may declare extends = "<base>" to start from another theme and override only the keys that differ. Inheritance is one level deep — a base that itself declares extends is an error. The built-in themes are self-contained (they do not use extends); inheritance is a convenience for your own themes.

name    = "midnight"
extends = "quiet"

[palette]
primary_accent = { light = "#5E60CE", dark = "#9D4EDD" }

A user theme that is missing keys the base does not supply is reported and falls back to quiet, so a theme always renders something complete.

Palette keys

Key	Used for
`base`, `surface`	Panel and elevated-surface backgrounds
`text_primary`	Active, high-emphasis text
`text_secondary`	Labels and metadata
`text_subtle`	Hints and disabled text
`border`	Panel borders
`selection`	The cursor-row highlight band
`primary_accent`	IDs, links, interactive elements
`secondary_accent`	Brand and callouts (progress fill, section headers)
`error`, `error_subtle`, `error_bright`	Failures; dimmed and cursor-row variants
`warning`	Drift and warnings
`unmanaged`	The `⚠ unmanaged` marker in `formae inventory`
`done`, `in_progress`, `pending`	Brightness-based state colors
`op_create`, `op_update`, `op_delete`, `op_replace`, `op_detach`, `op_keep`	Per-operation colors
`logo_wordmark`	When set, colors the “formae” letters of the logo; the propeller stays brand orange

Glyphs

The [glyphs] plane maps each semantic symbol to a character. Decorative separators and panel borders are fixed chrome and are not themeable.

Group	Keys
Operations	`op_create`, `op_update`, `op_delete`, `op_replace`, `op_detach`, `op_keep`
Status	`status_done`, `status_failed`, `status_pending`, `status_inprogress`, `status_skipped`, `status_canceled`
Acknowledgements	`ack_done`, `ack_skip`, `ack_warn`, `ack_fail`
Tree and disclosure	`tree_branch`, `tree_last`, `expand_open`, `expand_closed`
Miscellaneous	`checkbox_on`, `checkbox_off`, `transition`

Keep glyphs to single-width characters. Some symbols (such as …, ✗, ⚠) are East-Asian-ambiguous and render double-width in certain terminals, which can misalign side-by-side panels.

Progress and spinner

[progress]
fill_done       = "█"
fill_inprogress = "▓"
fill_pending    = "░"
animation       = "pulse"    # pulse | blink | static

[spinner]
frames      = ["⠋", "⠙", "⠹", "⠸"]   # explicit frames…
# preset    = "braille"                # …or a preset (frames wins if both are set)
interval_ms = 100
static_frame = "⠋"                     # used for non-animated / static rendering

Behavior toggles

[confirmation_bar]
color = "brand"      # brand | severity

[header]
highlight = "brighten"   # brighten | background

[rows]
label_accent     = false   # color the label column with primary_accent
delete_whole_row = false   # tint the entire row with op_delete on deletes

Setting	Values	Effect
`confirmation_bar.color`	`brand`, `severity`	`brand` always uses `secondary_accent`; `severity` colors the pre-execution confirmation bar by the most severe operation (delete or replace → `error`, else update → `op_update`, else `done`).
`header.highlight`	`brighten`, `background`	How the navigated/sorted column header is emphasized: `brighten` uses a bright foreground; `background` adds a highlight band.
`rows.label_accent`	`true`, `false`	Render the label column in `primary_accent` (a distinct identifier) instead of the same color as the other columns.
`rows.delete_whole_row`	`true`, `false`	Tint an entire delete row in `op_delete` so destructive changes stand out.

Minimal example

name = "midnight"

[palette]
primary_accent = { light = "#5E60CE", dark = "#9D4EDD" }
op_create      = { light = "#2A9D8F", dark = "#4ADE80" }
op_delete      = { light = "#D64545", dark = "#F87171" }

[glyphs]
op_create = "+"
op_delete = "-"

[progress]
fill_done       = "█"
fill_inprogress = "▓"
fill_pending    = "░"
animation       = "pulse"

[spinner]
frames      = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧"]
interval_ms = 100
static_frame = "⠋"

[confirmation_bar]
color = "brand"

[header]
highlight = "brighten"

[rows]
label_accent     = false
delete_whole_row = false

Save this as ~/.config/formae/themes/midnight.toml, then select it:

cli {
    theme = "midnight"
}

Get started

Guides

Concepts

Reference

Selecting a theme

Available themes

Light and dark appearance

Omarchy

Authoring a theme

Colors

Inheritance

Palette keys

Glyphs

Progress and spinner

Behavior toggles

Minimal example

​Selecting a theme

​Available themes

​Light and dark appearance

​Omarchy

​Authoring a theme

​Colors

​Inheritance

​Palette keys

​Glyphs

​Progress and spinner

​Behavior toggles

​Minimal example

Selecting a theme

Available themes

Light and dark appearance

Omarchy

Authoring a theme

Colors

Inheritance

Palette keys

Glyphs

Progress and spinner

Behavior toggles

Minimal example