TerminalCapabilities unstable

Detection of whether a CLI can color, animate, or prompt.

The default reads NO_COLOR, FORCE_COLOR, TERM, and the TTY state of the current process. The layer reads the same variables through ConfigProvider, plus the TTY state of Stdio. Unless a CliOutput.Formatter is provided, the built-in help, version, and error output of Command follows canColor.

3 exports Since v4.0.0 Source

Layers

layer

unstable

Since v4.0.0

Detects terminal capabilities from Stdio and the current ConfigProvider.

Details

TERM=dumb clears all three flags, because a terminal that cannot move the cursor can neither animate nor redraw a prompt. Otherwise NO_COLOR, when set to any non-empty value, disables color and wins over FORCE_COLOR. FORCE_COLOR forces color even off a TTY, except for 0 and false, which mean "not forcing". Empty variables count as unset, matching ConfigProvider.fromEnv, so FORCE_COLOR= does not force color on. canPrompt requires both standard input and standard output to be terminals. A ConfigProvider fault is a defect, so the layer never fails.

Signature

declare const layer: Layer.Layer<never, never, Stdio.Stdio>

Example NO_COLOR wins over FORCE_COLOR

import { ConfigProvider, Effect, Stdio } from "effect"
import { TerminalCapabilities } from "effect/cli"

const program = Effect.gen(function*() {
  const caps = yield* TerminalCapabilities.TerminalCapabilities
  return caps.canColor
}).pipe(
  Effect.provide(TerminalCapabilities.layer),
  Effect.provide(Stdio.layerTest({ stdoutIsTerminal: Effect.succeed(true) })),
  Effect.provideService(
    ConfigProvider.ConfigProvider,
    ConfigProvider.fromEnv({ env: { NO_COLOR: "1", FORCE_COLOR: "1" } })
  )
)

Effect.runSync(program) // => false

Models

TerminalCapabilities

interface unstable

Since v4.0.0

Terminal rendering flags for the current process.

Details

canColor says whether styling will be rendered rather than stored as bytes. canAnimate says whether output is being watched, so pacing means something. canPrompt says whether a question can be asked and answered. Only canColor is read by the built-in Command output; the other two are for application code that renders its own output.

Signature

interface TerminalCapabilities {
  readonly canAnimate: boolean;
  readonly canColor: boolean;
  readonly canPrompt: boolean;
}

Services

TerminalCapabilities

unstable

Since v4.0.0

Reference to the terminal capabilities of the current process.

When to use

Use when application output should share the built-in help, version, and error output's answer. Provide layer to detect through ConfigProvider and Stdio, or provide a value to override detection.

Details

The default is detected from the current process the first time it is read, so later changes to the environment do not affect it. Without a process global, every flag is false.

Signature

declare const TerminalCapabilities: Reference<TerminalCapabilities>