tui schema (1501-1650)

Canonical generated docsThis section is generated from caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.

TUI configuration — terminal dashboard settings.

Previous Next

Field path	Type	Required	Default	Canonical description
└ `tui.graphics.subpanel_tabs.background_position`	`string`	optional	center	Background image position anchor: center, top, bottom, left, right, etc..
└ `tui.graphics.subpanel_tabs.background_scale`	`string`	optional	fit_width	Background image scale mode: fit_width, fit_height, fit_longest, fit_shortest.
└ `tui.graphics.subpanel_tabs.background_width`	`string`	optional		Explicit background image width: <n>px or <n>cols. Preserves aspect ratio.
└ `tui.graphics.subpanel_tabs.background_height`	`string`	optional		Explicit background image height: <n>px, <n>rows, or <n>cols. Preserves aspect ratio.
└ `tui.graphics.subpanel_tabs.background_scale_factor`	`f64`	optional	1.0	Additional scale factor applied after scale mode.
└ `tui.graphics.subpanel_tabs.background_offset_x`	`f64`	optional	0.0	Horizontal offset as percentage of container width.
└ `tui.graphics.subpanel_tabs.background_offset_y`	`f64`	optional	0.0	Vertical offset as percentage of container height.
└ `tui.graphics.subpanel_tabs.background_offset_x_image`	`f64`	optional	0.0	Horizontal offset as percentage of rendered image width.
└ `tui.graphics.subpanel_tabs.background_offset_y_image`	`f64`	optional	0.0	Vertical offset as percentage of rendered image height.
└ `tui.graphics.subpanel_tabs.background_rotation`	`string`	optional	cycle	Rotation mode for multi-image backgrounds: cycle or random.
└ `tui.graphics.subpanel_tabs.blend_mode`	`string`	optional	split	Border join blend mode: split or overlap.
└ `tui.graphics.subpanel_tabs.blending_mode`	`string`	optional	normal	Composition blending mode for multi-layer surfaces: normal, multiply, screen, overlay, add.
└ `tui.graphics.subpanel_tabs.merge_into_previous_layer`	`bool`	optional	true	Composite this layer into the same raster as preceding layers.
└ `tui.graphics.subpanel_tabs.draw_above_cell_backgrounds`	`bool`	optional	false	Render this layer above kitty cell backgrounds.
└ `tui.graphics.subpanel_tabs.color`	`string`	optional	auto	Base color override: auto, hex (#rrggbb), or theme color (colorN).
└ `tui.graphics.subpanel_tabs.focused_color`	`string`	optional		Focused-state color override.
└ `tui.graphics.subpanel_tabs.selected_color`	`string`	optional		Selected-state color override.
└ `tui.graphics.subpanel_tabs.active_color`	`string`	optional		Active-state color override.
└ `tui.graphics.subpanel_tabs.material`	`map`	optional		Single-pass inset material; preserves semantic tint and alpha. Not desktop backdrop blur.
└ `tui.graphics.subpanel_tabs.material.kind`	`string`	optional	none	Finish: none, glass, satin, chrome, paper.
└ `tui.graphics.subpanel_tabs.material.depth`	`u8`	optional	18	Inset shadow strength, saturating percent.
└ `tui.graphics.subpanel_tabs.material.sheen`	`u8`	optional	12	Directional reflection strength, saturating percent.
└ `tui.graphics.subpanel_tabs.material.grain`	`u8`	optional	2	Stable microtexture strength, saturating percent.
└ `tui.graphics.subpanel_tabs.material.width`	`u16`	optional	18	Inset falloff width in logical raster pixels.
└ `tui.graphics.subpanel_tabs.material.motion`	`u8`	optional	0	Reflection/depth motion percent; requires background_animate and enabled animations. Zero stays static.
└ `tui.graphics.subpanel_tabs.inner_glow`	`map`	optional		Inner glow effect config for inner_glow background style.
└ `tui.graphics.subpanel_tabs.inner_glow.radius`	`u32`	optional	8	Glow spread radius in pixels.
└ `tui.graphics.subpanel_tabs.inner_glow.intensity`	`f64`	optional	0.5	Peak glow intensity 0.0–1.0.
└ `tui.graphics.subpanel_tabs.inner_glow.opacity`	`f64`	optional	0.6	Glow opacity 0.0–1.0.
└ `tui.graphics.subpanel_tabs.radial_glow`	`map`	optional		Radial glow effect config for radial_glow background style.
└ `tui.graphics.subpanel_tabs.radial_glow.anchor`	`string`	optional	center	Glow center anchor: center, top, top_right, right, bottom_right, bottom, bottom_left, left, top_left.
└ `tui.graphics.subpanel_tabs.radial_glow.radius`	`string`	optional	half_longest	Radius spec: half_width, half_height, half_longest, half_shortest, or absolute(N).
└ `tui.graphics.subpanel_tabs.radial_glow.intensity`	`f64`	optional	0.5	Peak glow intensity 0.0–1.0.
└ `tui.graphics.subpanel_tabs.radial_glow.opacity`	`f64`	optional	0.6	Glow opacity 0.0–1.0.
└ `tui.graphics.subpanel_tabs.scanline`	`map`	optional		CRT scanline effect config for scanlines background style.
└ `tui.graphics.subpanel_tabs.scanline.spacing`	`u32`	optional	3	Vertical spacing between scanlines in pixels.
└ `tui.graphics.subpanel_tabs.scanline.intensity`	`f64`	optional	0.5	Scanline darkness intensity 0.0–1.0.
└ `tui.graphics.subpanel_tabs.scanline.warp`	`f64`	optional	0.3	Sinusoidal warp curvature amount 0.0–1.0.
└ `tui.graphics.subpanel_tabs.padding`	`map`	optional		Inner padding in cells inside the border.
└ `tui.graphics.subpanel_tabs.padding.top`	`u16`	optional	0	Cells of padding above content.
└ `tui.graphics.subpanel_tabs.padding.bottom`	`u16`	optional	0	Cells of padding below content.
└ `tui.graphics.subpanel_tabs.padding.left`	`u16`	optional	0	Cells of padding left of content.
└ `tui.graphics.subpanel_tabs.padding.right`	`u16`	optional	0	Cells of padding right of content.
└ `tui.graphics.subpanel_tabs.disable_on_scroll`	`bool`	optional		Temporarily fall back to ASCII on scroll.
└ `tui.graphics.subpanel_tabs.min_height`	`u16`	optional	1	Minimum button height in cells. 1 = compact pill mode, 3+ = bordered mode.
└ `tui.graphics.subpanel_tabs.button_decoration_style`	`string`	optional	pill	Compact button decoration style: none, glow, box, pill, glass_pill. Used for 1-2 row buttons.
└ `tui.graphics.subpanel_tabs.animation_phase_offset`	`f32`	optional	0.0	Additive phase offset for animation cycle 0.0–1.0.
└ `tui.graphics.subpanel_tabs.overrides`	`map[string, map]`	optional		Per-instance style overrides keyed by instance name. Each value accepts the same fields as the parent style.
└ `tui.graphics.subpanel_tabs.active_overrides`	`map`	optional		Active/selected-state style overrides.
└ `tui.graphics.subpanel_tabs.inactive_overrides`	`map`	optional		Inactive-state style overrides for tab roles.
└ `tui.graphics.subpanel_tabs.focused_overrides`	`map`	optional		Focused-state style overrides.
└ `tui.graphics.button`	`map`	optional		Clickable button chrome style.
└ `tui.graphics.button.tint`	`string`	optional		Background tint color: hex (#rrggbb), match_border, or colorN.
└ `tui.graphics.button.tint_intensity`	`f64`	optional	0.15	Background tint blend intensity 0.0–1.0.
└ `tui.graphics.button.background_style`	`string`	optional	none	Background fill style: none, solid, or gradient.
└ `tui.graphics.button.background_opacity`	`f64`	optional	1.0	Background alpha multiplier for bitmap panel fills.
└ `tui.graphics.button.background_contrast`	`f64`	optional	1.08	Alternate background gradient brightness multiplier.
└ `tui.graphics.button.background_angle`	`f64`	optional	35.0	Gradient direction in degrees for bitmap panel fills.
└ `tui.graphics.button.background_animate`	`bool`	optional	false	Scroll the background gradient when animations are enabled.
└ `tui.graphics.button.background_animation_speed`	`f64`	optional	0.25	Background animation speed in cycles per second.
└ `tui.graphics.button.animation_speed`	`f64`	optional	0.25	Border animation speed in cycles per second, using the same units as background_animation_speed.
└ `tui.graphics.button.animation_frames`	`u16`	optional	96	Number of temporal phase buckets per animation cycle; speed controls cycle duration. Values above 255 require 16-bit-capable clients.
└ `tui.graphics.button.animation_style`	`string`	optional	pulse	Border animation style: pulse or rotating_gradient.
└ `tui.graphics.button.border_animation_style`	`string`	optional		Border-specific animation style override: pulse or rotating_gradient. Overrides animation_style for border perimeters only.
└ `tui.graphics.button.border_spacing`	`u32`	optional	100	Bias for how far strokes sit toward the outer edge of a border cell.
└ `tui.graphics.button.line_thickness`	`f64`	optional	1.0	Stroke thickness multiplier for bitmap borders.
└ `tui.graphics.button.pattern`	`string`	optional	solid	Stroke pattern: solid, diagonal_stripes, checkerboard, dashed, dotted, houndstooth, bevel, etched.
└ `tui.graphics.button.pattern_size`	`u32`	optional	3	Stroke pattern tile size in pixels at 1x scale.
└ `tui.graphics.button.pattern_opacity`	`f64`	optional	0.72	Alternate pattern alpha multiplier.
└ `tui.graphics.button.pattern_contrast`	`f64`	optional	0.86	Alternate pattern brightness multiplier.
└ `tui.graphics.button.glow`	`bool`	optional	false	Enable glow effect on bitmap borders.
└ `tui.graphics.button.glow_radius`	`u32`	optional	4	Glow spread radius in pixels at 1x scale.
└ `tui.graphics.button.glow_intensity`	`f64`	optional	0.35	Glow intensity multiplier.
└ `tui.graphics.button.pulse_low`	`f64`	optional	0.0	Minimum normalized oscillation point for animated border effects.
└ `tui.graphics.button.pulse_high`	`f64`	optional	1.0	Maximum normalized oscillation point for animated border effects.
└ `tui.graphics.button.shadow_intensity`	`f64`	optional	0.0	Drop-shadow intensity behind the bitmap stroke.
└ `tui.graphics.button.stroke_intensity`	`f64`	optional	0.0	Outline/stroke intensity around the bitmap stroke.
└ `tui.graphics.button.corner_radius`	`u32`	optional	4	Rounded corner radius in pixels at 1x scale.
└ `tui.graphics.button.title_gap_terminator`	`string`	optional	tick	Terminator style used when carving title gaps from top border runs: none, tick, tack, box, pill.
└ `tui.graphics.button.header_decoration_style`	`string`	optional	none	Text decoration style for header/title kitty surfaces: none, glow, box, pill, glass_pill.
└ `tui.graphics.button.header_decoration_thickness`	`f64`	optional	0.5	Thickness multiplier for header decoration strokes, relative to border thickness.
└ `tui.graphics.button.header_decoration_radius`	`u32`	optional	3	Corner radius for header decoration box/pill containers.
└ `tui.graphics.button.header_decoration_glow_radius`	`u32`	optional	2	Glow spread radius for header text glow decoration.
└ `tui.graphics.button.header_decoration_opacity`	`f64`	optional	0.6	Opacity multiplier for header decoration surfaces.
└ `tui.graphics.button.span_glow_enabled`	`bool`	optional	true	Enable span-level glow effects on header/footer text elements.
└ `tui.graphics.button.span_glow_radius`	`u32`	optional	2	Glow spread radius for span-level glow effects in cells.
└ `tui.graphics.button.span_glow_intensity`	`f64`	optional	0.35	Opacity/intensity multiplier for span-level glow effects.
└ `tui.graphics.button.span_glow_bleed_x`	`u16`	optional	2	Extra columns the glow image extends beyond text cells on each side.
└ `tui.graphics.button.span_glow_bleed_y`	`u16`	optional	1	Extra rows the glow image extends beyond text cells on each side.
└ `tui.graphics.button.foreground_color`	`string`	optional		Foreground color override for text/chrome in this role (hex or colorN).
└ `tui.graphics.button.background_color`	`string`	optional		Background color override for panel fills in this role (hex or colorN).
└ `tui.graphics.button.background_overlay`	`string`	optional	none	Composable overlay effect on top of background: none or scanlines.
└ `tui.graphics.button.background_overlay_opacity`	`f64`	optional	0.15	Overlay opacity/intensity 0.0–1.0.
└ `tui.graphics.button.background_image`	`string \| list[string]`	optional		Background image path or list of paths for rotation.
└ `tui.graphics.button.background_position`	`string`	optional	center	Background image position anchor: center, top, bottom, left, right, etc..
└ `tui.graphics.button.background_scale`	`string`	optional	fit_width	Background image scale mode: fit_width, fit_height, fit_longest, fit_shortest.
└ `tui.graphics.button.background_width`	`string`	optional		Explicit background image width: <n>px or <n>cols. Preserves aspect ratio.
└ `tui.graphics.button.background_height`	`string`	optional		Explicit background image height: <n>px, <n>rows, or <n>cols. Preserves aspect ratio.
└ `tui.graphics.button.background_scale_factor`	`f64`	optional	1.0	Additional scale factor applied after scale mode.
└ `tui.graphics.button.background_offset_x`	`f64`	optional	0.0	Horizontal offset as percentage of container width.
└ `tui.graphics.button.background_offset_y`	`f64`	optional	0.0	Vertical offset as percentage of container height.
└ `tui.graphics.button.background_offset_x_image`	`f64`	optional	0.0	Horizontal offset as percentage of rendered image width.
└ `tui.graphics.button.background_offset_y_image`	`f64`	optional	0.0	Vertical offset as percentage of rendered image height.
└ `tui.graphics.button.background_rotation`	`string`	optional	cycle	Rotation mode for multi-image backgrounds: cycle or random.
└ `tui.graphics.button.blend_mode`	`string`	optional	split	Border join blend mode: split or overlap.
└ `tui.graphics.button.blending_mode`	`string`	optional	normal	Composition blending mode for multi-layer surfaces: normal, multiply, screen, overlay, add.
└ `tui.graphics.button.merge_into_previous_layer`	`bool`	optional	true	Composite this layer into the same raster as preceding layers.
└ `tui.graphics.button.draw_above_cell_backgrounds`	`bool`	optional	false	Render this layer above kitty cell backgrounds.
└ `tui.graphics.button.color`	`string`	optional	auto	Base color override: auto, hex (#rrggbb), or theme color (colorN).
└ `tui.graphics.button.focused_color`	`string`	optional		Focused-state color override.
└ `tui.graphics.button.selected_color`	`string`	optional		Selected-state color override.
└ `tui.graphics.button.active_color`	`string`	optional		Active-state color override.
└ `tui.graphics.button.material`	`map`	optional		Single-pass inset material; preserves semantic tint and alpha. Not desktop backdrop blur.
└ `tui.graphics.button.material.kind`	`string`	optional	none	Finish: none, glass, satin, chrome, paper.
└ `tui.graphics.button.material.depth`	`u8`	optional	18	Inset shadow strength, saturating percent.
└ `tui.graphics.button.material.sheen`	`u8`	optional	12	Directional reflection strength, saturating percent.
└ `tui.graphics.button.material.grain`	`u8`	optional	2	Stable microtexture strength, saturating percent.
└ `tui.graphics.button.material.width`	`u16`	optional	18	Inset falloff width in logical raster pixels.
└ `tui.graphics.button.material.motion`	`u8`	optional	0	Reflection/depth motion percent; requires background_animate and enabled animations. Zero stays static.
└ `tui.graphics.button.inner_glow`	`map`	optional		Inner glow effect config for inner_glow background style.
└ `tui.graphics.button.inner_glow.radius`	`u32`	optional	8	Glow spread radius in pixels.
└ `tui.graphics.button.inner_glow.intensity`	`f64`	optional	0.5	Peak glow intensity 0.0–1.0.
└ `tui.graphics.button.inner_glow.opacity`	`f64`	optional	0.6	Glow opacity 0.0–1.0.
└ `tui.graphics.button.radial_glow`	`map`	optional		Radial glow effect config for radial_glow background style.
└ `tui.graphics.button.radial_glow.anchor`	`string`	optional	center	Glow center anchor: center, top, top_right, right, bottom_right, bottom, bottom_left, left, top_left.
└ `tui.graphics.button.radial_glow.radius`	`string`	optional	half_longest	Radius spec: half_width, half_height, half_longest, half_shortest, or absolute(N).
└ `tui.graphics.button.radial_glow.intensity`	`f64`	optional	0.5	Peak glow intensity 0.0–1.0.
└ `tui.graphics.button.radial_glow.opacity`	`f64`	optional	0.6	Glow opacity 0.0–1.0.
└ `tui.graphics.button.scanline`	`map`	optional		CRT scanline effect config for scanlines background style.
└ `tui.graphics.button.scanline.spacing`	`u32`	optional	3	Vertical spacing between scanlines in pixels.
└ `tui.graphics.button.scanline.intensity`	`f64`	optional	0.5	Scanline darkness intensity 0.0–1.0.
└ `tui.graphics.button.scanline.warp`	`f64`	optional	0.3	Sinusoidal warp curvature amount 0.0–1.0.
└ `tui.graphics.button.padding`	`map`	optional		Inner padding in cells inside the border.
└ `tui.graphics.button.padding.top`	`u16`	optional	0	Cells of padding above content.
└ `tui.graphics.button.padding.bottom`	`u16`	optional	0	Cells of padding below content.
└ `tui.graphics.button.padding.left`	`u16`	optional	0	Cells of padding left of content.
└ `tui.graphics.button.padding.right`	`u16`	optional	0	Cells of padding right of content.
└ `tui.graphics.button.disable_on_scroll`	`bool`	optional		Temporarily fall back to ASCII on scroll.
└ `tui.graphics.button.min_height`	`u16`	optional	1	Minimum button height in cells. 1 = compact pill mode, 3+ = bordered mode.
└ `tui.graphics.button.button_decoration_style`	`string`	optional	pill	Compact button decoration style: none, glow, box, pill, glass_pill. Used for 1-2 row buttons.
└ `tui.graphics.button.animation_phase_offset`	`f32`	optional	0.0	Additive phase offset for animation cycle 0.0–1.0.
└ `tui.graphics.button.overrides`	`map[string, map]`	optional		Per-instance style overrides keyed by instance name. Each value accepts the same fields as the parent style.
└ `tui.graphics.button.active_overrides`	`map`	optional		Active/selected-state style overrides.
└ `tui.graphics.button.inactive_overrides`	`map`	optional		Inactive-state style overrides for tab roles.
└ `tui.graphics.button.focused_overrides`	`map`	optional		Focused-state style overrides.
└ `tui.graphics.button_padding`	`u16 \| map`	optional		Button padding: uniform integer or { top, left, bottom, right } map.
└ `tui.ghostty`	`map`	optional		Ghostty host-terminal settings driven by the TUI. Rendered to $CACOPHONY_DIR/tui/caco.ghostty and applied by signalling the containing Ghostty window to reload (SIGUSR2); no-op unless the host terminal is Ghostty. Keys pass through verbatim as `key = value`.
└ `tui.ghostty.background`	`string`	optional		Ghostty window background color (hex, e.g. '#1b1d22'). The first well-known key; any other Ghostty config key may also be set and is rendered verbatim.
└ `tui.ghostty.shader`	`map`	optional		Live Ghostty custom-shader effects. Loads the bundled Lumen shader through caco.ghostty and streams TUI state through reserved palette slots 160-255; direct Ghostty hosts only.
└ `tui.ghostty.shader.enable`	`bool`	optional	false	Enable the live shader.

Previous Next