// @ozaco/cli

Palette

Environment-aware color and symbol implementations of the `Palette` protocol.

import from@ozaco/cli/palette

@ozaco/cli/palette provides the concrete Palette implementations the rest of the CLI renders through. A palette resolves two things: a set of ANSI colors (each a text => text styling function) and a set of symbols (unicode glyphs such as ❯ and ◉, or ascii fallbacks like > and (*)).

Both are auto-detected. Color is enabled unless NO_COLOR is set, disabled when FORCE_COLOR is 0/false or TERM=dumb, and otherwise follows whether the output is a TTY. Unicode is detected from the platform, terminal program and locale (LC_ALL/LC_CTYPE/LANG containing UTF-8). When color is disabled, every style becomes the identity function, so the same code prints clean output to a pipe or CI log.

Install DefaultPalette for the detected defaults, or build a themed one with definePalette — overriding individual colors, symbols, or forcing color/unicode on or off. Downstream modules read the active palette via Palette.actions.colors() / Palette.actions.symbols().

// on this page

Implementations Types

Implementations

Ready-to-install palettes and the factory for custom themes.

const

DefaultPalette

The auto-detecting palette — installs colors and symbols from the environment.

signature

const DefaultPalette: PaletteDef

Resolves color and unicode from the environment and TTY, then builds the standard color set and unicode-or-ascii symbol set. Install it once near program start; the spinner, prompt and table modules all pick it up from the scope.

example

import { install } from '@ozaco/std/plugin'
import { DefaultPalette } from '@ozaco/cli/palette'

yield* install(DefaultPalette)
// force behavior via options:
yield* install(DefaultPalette, { color: true, unicode: false })

definePalette

Build a themed `Palette` implementation, overriding colors, symbols or detection.

signature

function definePalette(definition?: DefinePaletteOptions): PaletteDef

Every field is optional. colors / symbols are shallow-merged over the detected defaults, so you can override just primary or just the pointer glyph. color / unicode force detection on or off. name / version label the resulting plugin. Install-time options take precedence over the definition’s defaults.

// parameters

definition?: DefinePaletteOptions

Theme overrides plus optional plugin `name`/`version`.

// returns A `PaletteDef` plugin you can `install`.

example

import { definePalette } from '@ozaco/cli/palette'

const BrandPalette = definePalette({
  name: 'app/brand-palette',
  colors: { primary: text => `\x1b[38;5;39m${text}\x1b[39m` },
  symbols: { pointer: '→' },
})

Types

iface

DefinePaletteOptions

Options accepted by `definePalette` — `PaletteDef.Options` plus plugin metadata.

signature

interface DefinePaletteOptions extends PaletteDef.Options {
  name?: string
  version?: string
  // inherited from PaletteDef.Options:
  color?: boolean
  unicode?: boolean
  colors?: Partial<PaletteDef.Colors>
  symbols?: Partial<PaletteDef.Symbols>
}

See PaletteDef.Colors / PaletteDef.Symbols in @ozaco/cli/core for the full set of overridable styles and glyphs.