CliOutput

Formats CLI help and errors as text.

This module turns help documents, CLI errors, grouped errors, and version information into strings. It does not write those strings to the terminal itself. It includes the Formatter interface, the formatter service, a layer for custom formatters, and the default formatter with configurable color support.

4 exports Added in v4.0.0 Source

Constructors

defaultFormatter

Added in v4.0.0 Source

Creates a default formatter with configurable options.

Signature

declare function defaultFormatter(options?: {
  colors?: boolean;
}): Formatter

Example

(Creating default formatters)

import { CliError, CliOutput } from "effect/unstable/cli"

// Create a formatter without colors for tests or CI environments
const noColorFormatter = CliOutput.defaultFormatter({ colors: false })

// Create a formatter with colors forced on
const colorFormatter = CliOutput.defaultFormatter({ colors: true })

// Auto-detect colors based on terminal support (default behavior)
const autoFormatter = CliOutput.defaultFormatter()

const error = new CliError.InvalidValue({
  option: "foo",
  value: "bar",
  expected: "baz",
  kind: "flag"
})

noColorFormatter.formatError(error).includes("Invalid value") // => true
colorFormatter.formatVersion("my-tool", "1.2.3").includes("my-tool") // => true
autoFormatter.formatVersion("my-tool", "1.2.3").includes("1.2.3") // => true

Layers

layer

Added in v4.0.0 Source

Creates a Layer that provides a custom Formatter implementation.

Signature

declare function layer(formatter: Formatter): Layer<never>

Example

(Providing a custom formatter)

import { Effect } from "effect"
import { CliOutput } from "effect/unstable/cli"

// Create a custom formatter without colors
const noColorFormatter = CliOutput.defaultFormatter({ colors: false })
const NoColorLayer = CliOutput.layer(noColorFormatter)

// Create a program that uses the custom formatter
const program = Effect.gen(function*() {
  const formatter = yield* CliOutput.Formatter
  return formatter.formatVersion("my-cli", "1.0.0")
}).pipe(
  Effect.provide(NoColorLayer)
)

await Effect.runPromise(program) // => "my-cli v1.0.0"

Models

Formatter interface

Added in v4.0.0 Source

Defines the service interface for formatting CLI output including help, errors, and version info. This allows customization of output formatting, including color support.

Signature

interface Formatter {
  readonly formatCliError: (error: CliError) => string;
  readonly formatError: (error: CliError) => string;
  readonly formatErrors: (errors: readonly Array<CliError>) => string;
  readonly formatHelpDoc: (doc: HelpDoc) => string;
  readonly formatVersion: (name: string, version: string) => string;
}

Example

(Customizing CLI output formatting)

import { Effect } from "effect"
import { CliOutput } from "effect/unstable/cli"

// Create a custom formatter implementation
const customFormatter: CliOutput.Formatter = {
  formatHelpDoc: (doc) => `Custom Help: ${doc.usage}`,
  formatCliError: (error) => `Error: ${error.message}`,
  formatError: (error) => `[ERROR] ${error.message}`,
  formatVersion: (name, version) => `${name} (${version})`,
  formatErrors: (errors) => errors.map((error) => error.message).join("\\n")
}

// Use the custom formatter in a program
const program = Effect.gen(function*() {
  const formatter = yield* CliOutput.Formatter
  return formatter.formatVersion("myapp", "1.0.0")
}).pipe(
  Effect.provide(CliOutput.layer(customFormatter))
)

await Effect.runPromise(program) // => "myapp (1.0.0)"

Services

Formatter

Added in v4.0.0 Source

Service reference for the CLI output formatter. Provides a default implementation that can be overridden for custom formatting or testing.

Signature

declare const Formatter: Reference<Formatter>

Example

(Accessing the output formatter)

import { Effect } from "effect"
import { CliOutput } from "effect/unstable/cli"

// Access the formatter service
const program = Effect.gen(function*() {
  const formatter = yield* CliOutput.Formatter

  // Format version information
  return formatter.formatVersion("my-cli", "2.1.0")
})

// Run with default formatter
await Effect.runPromise(program.pipe(
  Effect.provide(CliOutput.layer(CliOutput.defaultFormatter({ colors: false })))
)) // => "my-cli v2.1.0"