clog

A highly customizable structured logger for command-line tools with a zerolog-inspired fluent API, terminal-aware colors, hyperlinks, and animations.

Features

• Structured fields - typed field methods (Str, Int, Bool, Duration, JSON, …) with a fluent builder API
• Animations - spinners, progress bars, pulse, and shimmer effects with concurrent groups
• Hyperlinks - clickable file paths and URLs via OSC 8, with IDE presets for VS Code, Cursor, Sublime, and more
• JSON highlighting - syntax-highlighted JSON output with configurable rendering modes
• Styling - full visual customisation via lipgloss, including per-key, per-value, and per-type colors
• log/slog integration - drop-in slog.Handler backed by clog
• NO_COLOR - respects the NO_COLOR convention out of the box

Installation

go get github.com/gechr/clog

Quick Start

package main

import (
  "fmt"

  "github.com/gechr/clog"
)

func main() {
  clog.Info().Str("port", "8080").Msg("Server started")
  clog.Warn().Str("path", "/old").Msg("Deprecated endpoint")
  err := fmt.Errorf("connection refused")
  clog.Error().Err(err).Msg("Connection failed")
}

Output:

INF ℹ️ Server started port=8080
WRN ⚠️ Deprecated endpoint path=/old
ERR ❌ Connection failed error=connection refused

Levels

Built-in levels use gaps of 5 between them (except around Hint and Dry, which sit at 1 and 2), leaving room for custom levels at any position (see Custom Levels).

Setting the Level

// Programmatically
clog.SetLevel(clog.LevelDebug)

// From environment variable (CLOG_LOG_LEVEL is checked automatically on init)
// export CLOG_LOG_LEVEL=debug

Recognised CLOG_LOG_LEVEL values: trace, debug, info, hint, dry, warn, warning, error, fatal, critical.

Setting trace or debug also enables timestamps.

Parsing Levels

ParseLevel converts a string to a Level value (case-insensitive):

level, err := clog.ParseLevel("debug")

Level implements encoding.TextMarshaler and encoding.TextUnmarshaler, so it works directly with flag.TextVar and most flag libraries.

Non-TTY Level

When output is piped or running in CI (non-TTY), you may want to suppress lower-severity messages while keeping them visible during interactive use. SetNonTTYLevel sets a separate minimum level that only applies to non-TTY writers:

clog.SetNonTTYLevel(clog.LevelWarn)

This suppresses Trace, Debug, and Info events when stdout is not a terminal, but leaves them visible during interactive use. The setting also applies to animation progress lines (spinners, bars, etc.).

Pass UnsetLevel to remove the filter and restore default behaviour:

clog.SetNonTTYLevel(clog.UnsetLevel)

Custom Levels

Define custom levels at any numeric value between the built-in levels. Use RegisterLevel to configure the label, symbol, style, and canonical name.

const SuccessLevel clog.Level = clog.LevelDry + 1

func init() {
    clog.RegisterLevel(SuccessLevel, clog.LevelConfig{
        Name:   "success",
        Label:  "SCS",
        Symbol: "✅",
        Style:  new(lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("2"))),
    })
}

Log with clog.Log(level):

clog.Log(SuccessLevel).Msg("Build completed")
// SCS ✅ Build completed

Custom levels respect level filtering based on their numeric value. ParseLevel, MarshalText, and UnmarshalText all work with registered custom levels.

Use clog.Levels() to iterate all registered levels (built-in and custom) in ascending severity order.

Structured Fields

//# Structured Fields

Events and contexts support typed field methods. All methods are safe to call on a nil receiver (disabled events are no-ops).

Event Fields

Slice Formatting

Slice fields render as [a, b, c] by default. The brackets and separator are configurable:

clog.SetSliceSeparator(" ")        // [a b c]
clog.SetSliceBrackets('(', ')')    // (a, b, c)
clog.SetSliceBrackets('«', '»')    // «a, b, c»
clog.SetSliceBrackets('|', '|')    // |a, b, c| - same char for open and close

Duration Formatting

By default, Duration fields are hidden below DurationMinimum (time.Second), rounded to DurationRound (time.Second), and formatted with DurationPrecision (0 decimal places, e.g. 3s) - the same defaults as Elapsed fields. Durations >= 1m use composite format (e.g. 1m30s, 2h15m). Set the DurationFormat field of FieldFormats to apply a custom formatter per-logger instead:

f := clog.DefaultFieldFormats()
f.DurationFormat = commonutil.FormatDuration
clog.SetFieldFormats(f)

clog.Info().Duration("took", time.Since(start)).Msg("done")
// INF ℹ️ done took=2.3s

DurationFormat also applies as a fallback for Elapsed fields. See Elapsed Configuration for details.

Duration Gradient

Duration fields support the same green → yellow → red gradient as Elapsed fields. Enable it by setting a max duration:

f := clog.DefaultFieldFormats()
f.DurationGradientMax = 20 * time.Second
clog.SetFieldFormats(f)

clog.Info().Duration("duration", 2*time.Second).Msg("fast")    // green
clog.Info().Duration("duration", 10*time.Second).Msg("medium") // yellow
clog.Info().Duration("duration", 25*time.Second).Msg("slow")   // red (clamped)

When active, the gradient overrides FieldDurationNumber / FieldDurationUnit. See Duration Gradient in the styles reference for gradient mode and custom stop configuration.

Nested Fields (Dict)

Group related fields under a common key prefix using dot notation:

clog.Info().Dict("request", clog.Dict().
  Str("method", "GET").
  Int("status", 200),
).Msg("Handled")
// INF ℹ️ Handled request.method=GET request.status=200

Works with sub-loggers too:

logger := clog.With().Dict("db", clog.Dict().
  Str("host", "localhost").
  Int("port", 5432),
).Logger()

Finalising Events

clog.Info().Str("k", "v").Msg("message")  // Log with message
clog.Info().Str("k", "v").Msgf("n=%d", 5) // Log with formatted message
clog.Info().Str("k", "v").Send()           // Log with empty message
clog.Error().Err(err).Send()               // Log with error as message (no error= field)
clog.Error().Err(err).Msg("failed")        // Log with message + error= field

// Lazy message - fn only called when event is enabled:
clog.Debug().MsgFunc(func() string { return expensiveString() })

Styles

Customise the visual appearance using lipgloss styles:

clog.SetStyles(&style.Config{
  // Customise level colors
  Levels: style.LevelMap{
    clog.LevelError: new(
      lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("9")), // bright red
    ),
  },
  // Customise field key appearance
  KeyDefault: new(
    lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("12")), // bright blue
  ),
})

SetStyles merges non-zero fields into the existing configuration - only the fields you set are changed, all others keep their current values.

Value Coloring

Values are styled with a three-tier priority system:

1. Key styles - style all values of a specific field key
2. Value styles - style values matching a typed key (bool true != string "true")
3. Type styles - style values by their Go type

clog.SetStyles(&style.Config{
  // 1. Key styles: all values of the "status" field are green
  Keys: style.Map{
    "status": new(lipgloss.NewStyle().Foreground(lipgloss.Color("2"))),
  },
  // 2. Value styles: typed key matches (bool `true` != string "true")
  Values: style.ValueMap{
    "PASS": new(lipgloss.NewStyle().Foreground(lipgloss.Color("2"))),
    "FAIL": new(lipgloss.NewStyle().Foreground(lipgloss.Color("1"))),
  },
  // 3. Type styles
  FieldString: new(lipgloss.NewStyle().Foreground(lipgloss.Color("15"))),
  FieldNumber: new(lipgloss.NewStyle().Foreground(lipgloss.Color("5"))),
  FieldError:  new(lipgloss.NewStyle().Foreground(lipgloss.Color("1"))),
})

Styles Reference

Syntax Highlighting

Per-token styles for the Printer. Each has a Default*() constructor with Dracula-inspired colors. Set to nil to disable highlighting for that format.

See Printer for per-format token style tables.

Field Descriptions

Configuration

Behavioural settings are configured via setter methods on Logger (or package-level convenience functions for the Default logger):

Field formatting behaviour (gradient maxima, format functions, percent precision, hyperlink formats, etc.) is configured per-logger via the FieldFormats struct - see Field Formats.

Each Threshold pairs a minimum value with style overrides:

type ThresholdStyle struct {
  Number Style // Override for the number segment (nil = keep default).
  Unit   Style // Override for the unit segment (nil = keep default).
}

type Threshold struct {
  Value float64        // Minimum numeric value (inclusive) to trigger this style.
  Style ThresholdStyle // Style overrides for number and unit segments.
}

Thresholds are evaluated in descending order - the first match wins:

styles.QuantityThresholds["ms"] = style.Thresholds{
  {Value: 5000, Style: style.ThresholdStyle{Number: redStyle, Unit: redStyle}},
  {Value: 1000, Style: style.ThresholdStyle{Number: yellowStyle, Unit: yellowStyle}},
}

Value styles only apply at Info level and above by default. Use SetFieldStyleLevel to change the threshold.

Backtick Spans

Text inside a matched pair of backticks - in the message or in string field values - is rendered with the Backtick style. By default the delimiters are dropped (style.BacktickStrip), which shrinks the message by two visible columns per span. For pre-aligned content such as grid-padded table rows, use style.BacktickKeep to render the delimiters as part of the styled span, so the visible width is exactly what was written:

clog.SetStyles(&style.Config{BacktickMode: style.BacktickKeep})

An unmatched backtick is content, not a delimiter, and is left untouched in both modes. A non-color writer always leaves backticks exactly as written.

Per-Level Message Styles

Style the log message text differently for each level:

clog.SetStyles(&style.Config{
  Messages: style.LevelMap{
    clog.LevelError: new(lipgloss.NewStyle().Foreground(lipgloss.Color("1"))),
    clog.LevelWarn:  new(lipgloss.NewStyle().Foreground(lipgloss.Color("3"))),
  },
})

Use style.DefaultMessages() to get the defaults (unstyled for all levels).

Use style.DefaultValues() to get the default value styles (true=green, false=red, nil=grey, ""=grey).

Use style.DefaultPercentGradient() to get the default red → yellow → green gradient stops used for Percent fields.

Percent Gradient Direction

By default the Percent gradient runs red (0%) → yellow (50%) → green (100%) - useful when a higher value is better (e.g. battery, health score). For metrics where a lower value is better (CPU usage, disk usage, error rate), reverse the gradient:

// Logger-wide: all Percent fields
f := clog.DefaultFieldFormats()
f.PercentReverseGradient = true
clog.SetFieldFormats(f)

// Per-field: just this Percent field, regardless of the logger setting
clog.Info().
  Percent("cpu", 0.92, percent.WithReverseGradient()).
  Percent("battery", 0.85).
  Msg("System status")
// "cpu" renders red at 92%, "battery" renders green at 85%

percent.WithReverseGradient() is a percent.Option passed directly to Event.Percent. It toggles the logger’s PercentReverseGradient setting for that field - so if the gradient is already reversed, percent.WithReverseGradient() flips it back to normal. This makes it easy to mix metrics with different semantics on the same log line regardless of the logger default.

Duration Gradient

Color Duration fields on a gradient that transitions from green (fast) through yellow to red (slow). Set a max duration to enable the gradient - duration values are mapped onto 0→max, clamping at max:

f := clog.DefaultFieldFormats()
f.DurationGradientMax = 20 * time.Second
clog.SetFieldFormats(f)

When active, the gradient overrides FieldDurationNumber / FieldDurationUnit and colors the entire formatted string. When the max is 0 (the default) or DurationGradient stops are nil, the existing number/unit split styling is used.

Use style.DefaultElapsedGradient() to get the default green → yellow → red gradient stops (shared with Elapsed by default).

The DurationGradientMode field controls transition style - see Gradient Mode below.

Override the gradient max, stops, or transition mode for a single Duration field, regardless of the logger’s FieldFormats/style.Config settings, using options from the duration package:

import "github.com/gechr/clog/field/duration"

// Logger default: 20s gradient max
clog.SetDurationGradientMax(20 * time.Second)

clog.Info().
  Duration("latency", d).                                                 // uses the 20s default
  Duration("timeout_check", d2, duration.WithGradientMax(1*time.Second)). // this field maxes out at 1s
  Msg("request handled")

Elapsed Gradient

Color elapsed-time fields on a gradient that transitions from green (fast) through yellow to red (slow). Set a max duration to enable the gradient - elapsed values are mapped onto 0→max, clamping at max:

f := clog.DefaultFieldFormats()
f.ElapsedGradientMax = 30 * time.Second
clog.SetFieldFormats(f)

When active, the gradient overrides FieldElapsedNumber / FieldElapsedUnit and colors the entire formatted string. When the max is 0 (the default) or ElapsedGradient stops are nil, the existing number/unit split styling is used.

Use style.DefaultElapsedGradient() to get the default green → yellow → red gradient stops used for Elapsed fields (same stops as DurationGradient by default).

Per-Field Overrides

Override the gradient max, stops, or transition mode for a single Elapsed field, regardless of the logger’s FieldFormats/style.Config settings, using options from the elapsed package:

import "github.com/gechr/clog/field/elapsed"

// Logger default: 30s gradient max
clog.SetElapsedGradientMax(30 * time.Second)

clog.Info().
  Elapsed("elapsed").                                            // uses the 30s default
  Elapsed("quick_step", elapsed.WithGradientMax(2*time.Second)). // this field maxes out at 2s
  Msg("batch complete")

elapsed.WithGradient(stops...) overrides the color stops, and elapsed.WithGradientMode(mode) overrides fade vs. step transitions, for that field only:

clog.Info().Elapsed("elapsed",
  elapsed.WithGradientMax(5*time.Second),
  elapsed.WithGradient(
    style.ColorStop{Position: 0, Color: colorful.Color{R: 0, G: 1, B: 1}}, // cyan
    style.ColorStop{Position: 1, Color: colorful.Color{R: 1, G: 0, B: 1}}, // magenta
  ),
  elapsed.WithGradientMode(style.GradientStep),
).Msg("render")

elapsed.WithMinimum(d) overrides ElapsedMinimum for that field only - the field is hidden entirely when its duration falls below d, regardless of the logger’s threshold:

clog.SetElapsedMinimum(time.Second) // logger default: hide fields under 1s

clog.Info().
  Elapsed("elapsed").                               // hidden if under 1s
  Elapsed("critical_step", elapsed.WithMinimum(0)). // always shown
  Msg("batch complete")

These options work the same way on animated builders - fx.Builder.Elapsed (see Spinner) accepts the same elapsed.Option values for its auto-updating field.

The duration package mirrors this for Duration fields: duration.WithGradientMax, duration.WithGradient, duration.WithGradientMode (see Duration Gradient above), and duration.WithMinimum, which overrides DurationMinimum for that field only.

Gradient Mode

Both DurationGradientMode and ElapsedGradientMode control how colors transition between stops:

Fade blends smoothly between adjacent color stops using perceptually uniform CIE-LCh interpolation. Step uses the color of the last stop whose position is ≤ the current value - no blending.

clog.SetStyles(&style.Config{ElapsedGradientMode: style.GradientStep})

Custom Stops

clog.SetStyles(&style.Config{
  ElapsedGradient: []style.ColorStop{
    {Position: 0, Color: colorful.Color{R: 0, G: 1, B: 0}}, // green
    {Position: 1, Color: colorful.Color{R: 1, G: 0, B: 0}}, // red
  },
})

Format Hooks

Override the default formatting for Elapsed and Percent fields via FieldFormats:

f := clog.DefaultFieldFormats()

// Custom elapsed format: truncate to whole seconds
f.ElapsedFormat = func(d time.Duration) string {
  return d.Truncate(time.Second).String()
}

// Custom percent format: "75/100" instead of "75%"
f.PercentFormat = func(v float64) string {
  return fmt.Sprintf("%.0f/100", v)
}

clog.SetFieldFormats(f)

When set to nil (the default), the built-in formatters are used (formatElapsed with ElapsedPrecision for elapsed, strconv.FormatFloat with PercentPrecision + “%” for percent). Custom percent format functions receive the display percentage (0–100), not the raw stored value.

Field Sort Order

Control the order fields appear in log output. By default fields preserve insertion order.

// Sort fields alphabetically by key
clog.SetFieldSort(clog.SortAscending)

// Or reverse alphabetical
clog.SetFieldSort(clog.SortDescending)

clog.Info().
  Str("zoo", "animals").
  Str("alpha", "first").
  Int("count", 42).
  Msg("Sorted")
// SortNone:       INF ℹ️ Sorted zoo=animals alpha=first count=42
// SortAscending:  INF ℹ️ Sorted alpha=first count=42 zoo=animals
// SortDescending: INF ℹ️ Sorted zoo=animals count=42 alpha=first

Hyperlinks

Render clickable terminal hyperlinks using OSC 8 escape sequences:

// Typed field methods (recommended)
clog.Info().Path("dir", "src/").Msg("Directory")
clog.Info().Line("file", "config.yaml", 42).Msg("File with line")
clog.Info().Column("loc", "main.go", 42, 10).Msg("File with line and column")
clog.Info().URL("docs", "https://example.com/docs").Msg("See docs")
clog.Info().Link("docs", "https://example.com", "docs").Msg("URL")

// Slice variants
clog.Info().URLs("refs", []string{"https://a.com", "https://b.com"}).Msg("References")
clog.Info().Links("repos", []clog.Link{
    {URL: "https://github.com/foo/bar", Text: "foo/bar"},
    {URL: "https://github.com/baz/qux", Text: "baz/qux"},
}).Msg("Repositories")

// Standalone functions (for use with Str)
link := clog.PathLink("config.yaml", 42)               // file path with line number
link := clog.PathLink("src/", 0)                       // directory (no line number)
link := clog.Hyperlink("https://example.com", "docs")  // arbitrary URL

IDE Integration

Configure hyperlinks to open files directly in your editor via FieldFormats:

f := clog.DefaultFieldFormats()

// Generic fallback for any path (file or directory)
f.HyperlinkPathFormat = "vscode://file{path}"

// File-specific (overrides path format for files)
f.HyperlinkFileFormat = "vscode://file{path}"

// Directory-specific (overrides path format for directories)
f.HyperlinkDirFormat = "finder://{path}"

// File+line hyperlinks (Line, PathLink with line > 0)
f.HyperlinkLineFormat = "vscode://file{path}:{line}"
f.HyperlinkLineFormat = "idea://open?file={path}&line={line}"

// File+line+column hyperlinks (Column)
f.HyperlinkColumnFormat = "vscode://file{path}:{line}:{column}"

clog.SetFieldFormats(f)

Use {path}, {line}, and {column} (or {col}) as placeholders. Default format is file://{path}.

Format resolution order:

These can also be set via environment variables:

export CLOG_HYPERLINK_FORMAT="vscode"                      # named preset (sets all slots)
export CLOG_HYPERLINK_PATH_FORMAT="vscode://{path}"        # generic fallback
export CLOG_HYPERLINK_FILE_FORMAT="vscode://file{path}"    # files only
export CLOG_HYPERLINK_DIR_FORMAT="finder://{path}"         # directories only
export CLOG_HYPERLINK_LINE_FORMAT="vscode://{path}:{line}"
export CLOG_HYPERLINK_COLUMN_FORMAT="vscode://{path}:{line}:{column}"

CLOG_HYPERLINK_FORMAT accepts a preset name and configures all slots at once. Individual format vars override the preset for their specific slot. Environment variables apply to the Default logger’s FieldFormats.

Named Presets

Hyperlink format fields accept a preset name (e.g. "vscode") in place of a full format string - it is expanded for that slot when SetFieldFormats is called:

f := clog.DefaultFieldFormats()
f.HyperlinkLineFormat = "vscode"
clog.SetFieldFormats(f)

To apply a preset to all format slots at once, use hyperlink.Preset (or set CLOG_HYPERLINK_FORMAT=vscode in the environment):

import "github.com/gechr/clog/field/hyperlink"

cfg, err := hyperlink.Preset("vscode")
if err != nil {
  // unknown preset name
}

f := clog.DefaultFieldFormats()
f.HyperlinkPathFormat = cfg.PathFormat
f.HyperlinkFileFormat = cfg.FileFormat
f.HyperlinkDirFormat = cfg.DirFormat
f.HyperlinkLineFormat = cfg.LineFormat
f.HyperlinkColumnFormat = cfg.ColumnFormat
clog.SetFieldFormats(f)

Enabling / Disabling

Hyperlinks are enabled by default (when colors are active). Disable them programmatically:

f := clog.DefaultFieldFormats()
f.HyperlinkEnabled = false // disable all hyperlink rendering
clog.SetFieldFormats(f)

Hyperlinks are automatically disabled when colors are disabled.

Sub-loggers & Context

Sub-loggers

Create sub-loggers with preset fields using the With() context builder:

logger := clog.With().Str("component", "auth").Logger()
logger.Info().Str("user", "john").Msg("Authenticated")
// INF ℹ️ Authenticated component=auth user=john

Context fields support the same typed methods as events.

Context Propagation

Store a logger in a context.Context and retrieve it deeper in the call stack:

logger := clog.With().Str("request_id", "abc-123").Logger()
ctx := logger.WithContext(ctx)

// later, in any function that receives ctx:
clog.Ctx(ctx).Info().Msg("Handling request")
// INF ℹ️ Handling request request_id=abc-123

Ctx returns clog.Default when the context is nil or contains no logger, so it is always safe to call.

A package-level WithContext convenience stores clog.Default:

ctx := clog.WithContext(ctx) // stores clog.Default

Input

Prompt for a line of input from the terminal:

name, err := clog.Input("Name: ")

Input writes the prompt to the logger’s output, then reads a line from its input (os.Stdin by default). Reading is a plain newline-delimited read - the terminal’s own canonical line editing already provides backspace, Ctrl-U, and Ctrl-W for free, and Ctrl-C terminates the process exactly as it would at any other prompt, so Input never hangs waiting for input that isn’t coming.

Prompt from one goroutine at a time: Input and Password are not safe for concurrent use, and log lines emitted from other goroutines while a prompt is pending may interleave with it.

Password

Password is Input with typed characters not echoed to the screen, via term.ReadPassword:

pass, err := clog.Password("Password: ")

term.ReadPassword only disables local echo; it leaves the terminal’s own Ctrl-C/Ctrl-Z handling intact, so Password deliberately defers to it rather than a bespoke raw-mode reader. Outside of a real terminal (piped input, tests), Password behaves exactly like Input - there’s no echo to suppress.

Options

Both Input and Password accept InputOption values. Password is exactly Input with clog.WithSensitive(true) applied:

secret, err := clog.Input("Token: ", clog.WithSensitive(true))

Testing

SetInput overrides the reader Input/Password read from, so prompts can be driven in tests without a real terminal:

clog.SetInput(strings.NewReader("alice\n"))
name, _ := clog.Input("Name: ") // "alice", no TTY required

Per-logger usage

Input and Password are also available on any *clog.Logger:

logger := clog.NewWriter(os.Stdout)
name, err := logger.Input("Name: ")

Hooks

Hooks let you run code at specific points in the log write lifecycle. Register them with AddHook and a HookPoint.

Hook Points

Usage

// Clear a spinner line before log output
clog.AddHook(clog.HookBeforeWrite, func() {
    fmt.Print("\r\033[K")
})

// Restore a prompt after log output
clog.AddHook(clog.HookAfterWrite, func() {
    fmt.Print(">>> ")
})

Multiple hooks per point run in registration order.

Clearing Hooks

clog.ClearHooks(clog.HookBeforeWrite) // clear one point
clog.ClearAllHooks()                  // clear all points

Notes

• Hooks are called under the logger’s mutex - they must not call back into the same logger.
• Hooks fire for all log levels and for both the built-in formatter and custom handlers.
• Sub-loggers inherit parent hooks.
• Per-logger methods: logger.AddHook(point, fn), logger.ClearHooks(point), logger.ClearAllHooks().

Handlers

Implement the Handler interface for custom output formats:

type Handler interface {
  Log(Entry)
}

The Entry struct provides Level, Time, Message, Symbol, Indent, Tree, and Fields. The logger handles level filtering, field accumulation, timestamps, and locking - the handler only formats and writes.

// Using HandlerFunc adapter
clog.SetHandler(clog.HandlerFunc(func(e clog.Entry) {
  data, _ := json.Marshal(e)
  fmt.Println(string(data))
}))

Example output:

{"level":"info","symbol":"ℹ️","message":"Server started","fields":[{"key":"port","value":"8080"}]}

Level serializes as a human-readable string (e.g. "info", "error"). Time is omitted when timestamps are disabled. Symbol, Indent, Tree, and Fields are omitted when empty/zero.

log/slog Integration

Use sloghandler.New to create a slog.Handler backed by a clog logger. This lets any code that accepts slog.Handler or *slog.Logger produce clog-formatted output.

import "github.com/gechr/clog/sloghandler"

h := sloghandler.New(clog.Default, nil)
logger := slog.New(h)

logger.Info("request handled", "method", "GET", "status", 200)
// INF ℹ️ request handled method=GET status=200

Options

h := sloghandler.New(clog.Default, &sloghandler.Options{
  AddSource: true,           // include source file:line in each entry
  Level:     slog.LevelWarn, // override minimum level (nil = use logger's level)
})

Level Mapping

Records mapped to LevelFatal are logged but do not call os.Exit - only clog’s own Fatal().Msg() does that.

Groups and Attrs

WithGroup and WithAttrs work as expected. Groups use dot-notation keys matching clog’s Dict() pattern:

import "github.com/gechr/clog/sloghandler"

h := sloghandler.New(clog.Default, nil)
logger := slog.New(h).WithGroup("req")

logger.Info("handled", "method", "GET", "status", 200)
// INF ℹ️ handled req.method=GET req.status=200

Part Order

Control which parts appear in log output and in what order. The default order is: timestamp, level, symbol, message, fields.

// Reorder: show message before level
clog.SetParts(clog.PartMessage, clog.PartLevel, clog.PartSymbol, clog.PartFields)

// Hide parts by omitting them
clog.SetParts(clog.PartLevel, clog.PartMessage, clog.PartFields) // no symbol or timestamp

// Fields before message
clog.SetParts(clog.PartLevel, clog.PartFields, clog.PartMessage)

Available parts: PartTimestamp, PartLevel, PartSymbol, PartMessage, PartFields.

Use DefaultParts() to get the default ordering. Parts omitted from the list are hidden.

Per-Event Override

Override the part order for a single log event without mutating the logger:

// This event shows only the symbol and message - no level label or fields.
clog.Info().Parts(clog.PartSymbol, clog.PartMessage).Msg("hello")

// Other events still use the logger's default parts.
clog.Info().Msg("world")

This is useful when a particular message needs different formatting (e.g. a banner or status line) without creating a separate logger or calling SetParts.

The same .Parts() method is available on animations and their results:

// Spinner - both animation and completion use overridden parts.
clog.Spinner("loading").
  Parts(clog.PartSymbol, clog.PartMessage).
  Wait(ctx, fn).
  Msg("done")

// Override only on the completion message.
clog.Spinner("loading").
  Wait(ctx, fn).
  Parts(clog.PartMessage).
  Msg("done")

See Spinner and Group for more details.

Custom Labels

Override the default level labels with SetLabels:

clog.SetLabels(clog.LabelMap{
  clog.LevelInfo:  "INFO",
  clog.LevelWarn:  "WARNING",
  clog.LevelError: "ERROR",
})

Missing levels fall back to the defaults. Use DefaultLabels() to get a copy of the default label map.

Level Alignment

When custom labels have different widths, control alignment with SetLevelAlign:

clog.SetLevelAlign(clog.AlignRight)   // default: "   INFO", "WARNING", "  ERROR"
clog.SetLevelAlign(clog.AlignLeft)    //          "INFO   ", "WARNING", "ERROR  "
clog.SetLevelAlign(clog.AlignCenter)  //          " INFO  ", "WARNING", " ERROR "
clog.SetLevelAlign(clog.AlignNone)    //          "INFO",    "WARNING", "ERROR"

Custom Symbol

Override the default emoji symbol per-event, per-logger, or globally:

// Per-event
clog.Info().Symbol("📦").Str("pkg", "clog").Msg("Installed")

// Per-logger (via sub-logger)
logger := clog.With().Symbol("🛡️").Str("component", "auth").Logger()
logger.Info().Msg("Ready")

// Global (changes defaults for all levels)
clog.SetSymbols(clog.LabelMap{
  clog.LevelInfo:  ">>",
  clog.LevelWarn:  "!!",
  clog.LevelError: "XX",
})

During animations, SetSymbol on the Update changes the icon mid-task:

update.SetSymbol("📡").Str("stage", "receiving").Send()

Symbol resolution order: event override > logger preset > default emoji for level.

Missing levels in SetSymbols fall back to the defaults. Use DefaultSymbols() to get a copy of the default symbol map.

Styling Symbols

Symbols can be any string - not just emojis. Use Styles.Symbols to apply a lipgloss style per level:

clog.SetStyles(&style.Config{
  Symbols: style.LevelMap{
    clog.LevelInfo:  new(lipgloss.NewStyle().Foreground(lipgloss.Color("2"))), // green
    clog.LevelWarn:  new(lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("3"))), // yellow
    clog.LevelError: new(lipgloss.NewStyle().Foreground(lipgloss.Color("1"))), // red
  },
})

Symbol styles also apply to spinner animation frames, so spinners inherit the color of their level.

Styles.Symbols is a LevelMap. Entries for levels not in the map render unstyled (the default).

Custom Levels

Define custom log levels at any numeric value between the built-in levels. Built-in levels use gaps of 5, so there is plenty of room.

Registering a Custom Level

const SuccessLevel clog.Level = clog.LevelDry + 1

func init() {
    clog.RegisterLevel(SuccessLevel, clog.LevelConfig{
        Name:   "success", // required: canonical name for ParseLevel/MarshalText
        Label:  "SCS", // short display label (default: uppercase Name, max 3 chars)
        Symbol: "✅", // emoji symbol (default: "")
        Style:  new(lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("2"))),
    })
}

Logging with a Custom Level

Use Log(level) instead of the named methods:

clog.Log(SuccessLevel).Str("pkg", "api").Msg("Build completed")
// SCS ✅ Build completed pkg=api

Level Filtering

Custom levels respect the same filtering rules as built-in levels. A custom level with value 3 (between LevelDry at 2 and LevelWarn at 5) is visible when the minimum level is LevelInfo but hidden when the minimum level is LevelWarn or higher.

ParseLevel and Marshalling

Registered custom levels work with ParseLevel, MarshalText, and UnmarshalText:

level, err := clog.ParseLevel("success") // returns SuccessLevel

Iterating All Levels

Since built-in levels use gaps, level++ iteration will not work. Use Levels() instead:

for _, level := range clog.Levels() {
    fmt.Println(level) // prints all levels in ascending severity order
}

Quoting

By default, field values containing spaces or special characters are wrapped in Go-style double quotes ("hello world"). This behaviour can be customised with SetQuote.

Quote Modes

// Default: only quote when needed
clog.Info().Str("reason", "timeout").Str("msg", "hello world").Msg("test")
// INF ℹ️ test reason=timeout msg="hello world"

// Always quote string values
clog.SetQuote(clog.QuoteAlways)
clog.Info().Str("reason", "timeout").Msg("test")
// INF ℹ️ test reason="timeout"

// Never quote
clog.SetQuote(clog.QuoteNever)
clog.Info().Str("msg", "hello world").Msg("test")
// INF ℹ️ test msg=hello world

Custom Quote Character

Use a different character for both sides by passing the same rune twice:

clog.SetQuoteChars('\'', '\'')
clog.Info().Str("msg", "hello world").Msg("test")
// INF ℹ️ test msg='hello world'

Asymmetric Quote Characters

Use different opening and closing characters:

clog.SetQuoteChars('«', '»')
clog.Info().Str("msg", "hello world").Msg("test")
// INF ℹ️ test msg=«hello world»

clog.SetQuoteChars('[', ']')
clog.Info().Str("msg", "hello world").Msg("test")
// INF ℹ️ test msg=[hello world]

Smart Quoting

Enable smart quoting to pick a delimiter per value instead of escaping. Each quoted value is wrapped in the first delimiter that does not occur in it, so the output stays escape-free:

clog.SetSmartQuotes(true)
clog.Info().Str("msg", `plain value`).Msg("test")
// INF ℹ️ test msg="plain value"

clog.Info().Str("msg", `say "hi"`).Msg("test")
// INF ℹ️ test msg='say "hi"'

clog.Info().Str("msg", `it's a "test"`).Msg("test")
// INF ℹ️ test msg=`it's a "test"`

The default preference order is ", then ', then `. When a value contains all of them (or a backslash or a non-printable character, which cannot be wrapped literally), smart quoting falls back to Go-style escaped quoting via strconv.Quote.

Custom Preference Order

Override the order with SetSmartQuoteChars. Each QuotePair may use distinct opening and closing runes (a zero Close mirrors Open):

clog.SetSmartQuotes(true)
clog.SetSmartQuoteChars(
	clog.QuotePair{Open: '«', Close: '»'},
	clog.QuotePair{Open: '['},
)
clog.Info().Str("msg", "hello world").Msg("test")
// INF ℹ️ test msg=«hello world»

clog.Info().Str("msg", "a » b").Msg("test")
// INF ℹ️ test msg=[a » b]

Passing no pairs restores the default order. Smart quoting takes precedence over SetQuoteChars.

Styling Delimiters

By default the quote delimiters share the styling of the value they wrap. Set a FieldQuote style (see Styles) to control them independently:

// Replace: delimiters are dim, regardless of the value's color.
clog.SetStyles(&style.Config{
  FieldQuote: &style.QuoteStyle{
    Style: lipgloss.NewStyle().Faint(true),
  },
})

// Inherit: delimiters keep the value's color but add their own attributes.
clog.SetStyles(&style.Config{
  FieldQuote: &style.QuoteStyle{
    Style:   lipgloss.NewStyle().Bold(true),
    Inherit: true,
  },
})

With Inherit set, the value’s resolved style (which varies by type - string, error, number - and by per-key/per-value overrides) is used as the base, and only the attributes you set on Style are layered on top.

Quoting applies to individual field values and to elements within string and []any slices. All quoting settings are inherited by sub-loggers. Pass 0 to reset to the default (strconv.Quote).

Omit Empty / Zero

OmitEmpty

OmitEmpty omits fields that are semantically “nothing”: nil, empty strings "", and nil or empty slices and maps.

clog.SetOmitEmpty(true)
clog.Info().
  Str("name", "alice").
  Str("nickname", "").   // omitted
  Any("role", nil).      // omitted
  Int("age", 0).         // kept (zero but not empty)
  Bool("admin", false).  // kept (zero but not empty)
  Msg("User")
// INF ℹ️ User name=alice age=0 admin=false

OmitZero

OmitZero is a superset of OmitEmpty - it additionally omits 0, false, 0.0, zero durations, and any other typed zero value.

clog.SetOmitZero(true)
clog.Info().
  Str("name", "alice").
  Str("nickname", "").   // omitted
  Any("role", nil).      // omitted
  Int("age", 0).         // omitted
  Bool("admin", false).  // omitted
  Msg("User")
// INF ℹ️ User name=alice

Both settings are inherited by sub-loggers created with With(). When both are enabled, OmitZero takes precedence.

Both settings also apply to animated task rows (Task, Group tasks, progress bars): an empty field stays hidden while the row is live and appears in place - preserving its declared position - once it is given a value via a live Update or the task result. This makes it possible to reserve a slot for a late-arriving field (e.g. a URL) ahead of elapsed without rendering an empty url= in the meantime.

Elapsed

Measure and log the elapsed duration of an operation without animations:

e := clog.Info().Elapsed("elapsed")
runMigrations()
e.Msg("database migration")
// INF ℹ️ database migration elapsed=2s

Use Elapsed when you want elapsed-time logging but don’t need a spinner, progress bar, or any visual animation. The elapsed field uses the same formatting, styling, and field type as animation Elapsed fields.

Finalising

Elapsed events can be finalised with Send (no message), Msg, or Msgf:

e := clog.Info().Elapsed("elapsed")
runMigrations()
e.Send()
// INF ℹ️ elapsed=2s

e = clog.Info().Elapsed("elapsed")
runMigrations()
e.Msg("migrations complete")
// INF ℹ️ migrations complete elapsed=2s

Field Positioning

Elapsed can appear anywhere in the field chain to control where the elapsed field is shown:

// Elapsed before other fields
e := clog.Info().Elapsed("elapsed").Str("env", "prod")
deploy()
e.Msg("deploy")
// INF ℹ️ deploy elapsed=12s env=prod

// Elapsed after other fields
e = clog.Info().Str("env", "prod").Elapsed("elapsed")
deploy()
e.Msg("deploy")
// INF ℹ️ deploy env=prod elapsed=12s

On animated builders (fx.Builder), fields added at runtime via a live update always render after the builder’s base fields - use elapsed.Trailing() to pin the elapsed field to the end of the row regardless (see Spinner).

Custom Key

The key parameter controls the field name:

e := clog.Info().Elapsed("duration")
compile()
e.Msg("compile")
// INF ℹ️ compile duration=3s

Log Levels

Since Elapsed is a method on events, you control the level directly:

clog.Warn().Elapsed("elapsed").Msg("slow query")
// WRN ⚠️ slow query elapsed=5s

clog.Error().Elapsed("elapsed").Err(err).Msg("compile")
// ERR ❌ compile elapsed=3s error="syntax error"

Sub-loggers

Elapsed works on any logger instance:

logger := clog.With().Str("component", "db").Logger()
e := logger.Info().Elapsed("elapsed")
runQuery()
e.Msg("query")
// INF ℹ️ query component=db elapsed=1s

Elapsed Configuration

The elapsed field respects the same per-logger FieldFormats configuration as animation elapsed fields:

ElapsedGradientMax, ElapsedMinimum, and the ElapsedGradient/ElapsedGradientMode style settings, can also be overridden per field with options from the elapsed package - see Per-Field Overrides. The duration package mirrors this for Duration fields, including duration.WithMinimum:

import "github.com/gechr/clog/field/elapsed"

e := clog.Info().Elapsed("elapsed",
  elapsed.WithGradientMax(5*time.Second),
  elapsed.WithMinimum(0), // always show this field, regardless of the logger default
)
runMigrations()
e.Msg("database migration")

Duration Format Function

DurationFormat configures a single format function that applies to both Duration fields and Elapsed fields. This is useful when you have a shared helper (e.g. from a utility package) that you want applied consistently across all duration logging:

f := clog.DefaultFieldFormats()
f.DurationFormat = commonutil.FormatDuration
clog.SetFieldFormats(f)

// Both of these now use commonutil.FormatDuration:
clog.Info().Duration("took", time.Since(start)).Msg("done")
// INF ℹ️ done took=2.3s

e := clog.Info().Elapsed("elapsed")
doWork()
e.Msg("done")
// INF ℹ️ done elapsed=2.3s

When ElapsedFormat is also set, it takes priority over DurationFormat for Elapsed fields only. Duration fields always use DurationFormat:

f := clog.DefaultFieldFormats()
f.DurationFormat = func(d time.Duration) string { return "dur:" + d.String() }
f.ElapsedFormat = func(d time.Duration) string { return "ela:" + d.String() }
clog.SetFieldFormats(f)

clog.Info().Duration("latency", 3*time.Second).Msg("request")
// INF ℹ️ request latency=dur:3s  ← uses DurationFormat

e := clog.Info().Elapsed("elapsed")
e.Msg("done")
// INF ℹ️ done elapsed=ela:3s    ← ElapsedFormat takes priority

NO_COLOR

clog respects the NO_COLOR convention. When the NO_COLOR environment variable is set (any value, including empty), all colors and hyperlinks are disabled.

Color Control

Color behaviour is set per-Output via ColorMode:

// Package-level (recreates Default logger's Output)
clog.SetColorMode(clog.ColorAlways) // force colors (overrides NO_COLOR)
clog.SetColorMode(clog.ColorNever)  // disable all colors and hyperlinks
clog.SetColorMode(clog.ColorAuto)   // detect terminal capabilities (default)

// Per-logger via Output
logger := clog.New(clog.NewOutput(os.Stdout, clog.ColorAlways))

This is useful in tests to verify hyperlink output without mutating global state:

l := clog.New(clog.NewOutput(&buf, clog.ColorAlways))
l.Info().Line("file", "main.go", 42).Msg("Loaded")
// buf contains OSC 8 hyperlink escape sequences

ColorMode implements encoding.TextMarshaler and encoding.TextUnmarshaler, so it works directly with flag.TextVar and most flag libraries.

Piped stdout

When stdout is piped (non-TTY) but stderr is a terminal, clog still renders colors correctly. In lipgloss v2, styles are plain value types that always emit full-fidelity ANSI – color downsampling happens at the output layer. This means styles work correctly on stderr even when stdout is redirected:

// Colors work on stderr even when stdout is piped.
logger := clog.New(clog.Stderr(clog.ColorAuto))
logger.Info().Str("status", "ok").Msg("Ready")

Indentation

Create visually nested output where the message text shifts right while level, timestamp, and prefix columns stay fixed.

SetIndent

Set the indent depth directly on any logger:

logger.SetIndent(1)
logger.Info().Msg("indented")
// INF ℹ️   indented

logger.SetIndent(0) // back to normal

Sub-logger Indent

Use Indent() on a context builder to add one indent level (2 spaces by default). It’s chainable:

clog.Info().Msg("Building project")

build := clog.With().Indent().Logger()
build.Info().Msg("Compiling main.go")
build.Info().Msg("Compiling util.go")

link := build.With().Indent().Logger()
link.Info().Msg("Linking binary")

clog.Info().Msg("Build complete")

INF ℹ️ Building project
INF ℹ️   Compiling main.go
INF ℹ️   Compiling util.go
INF ℹ️     Linking binary
INF ℹ️ Build complete

Dedent

Use Dedent() to remove one indent level from a context builder. It is the mirror of Indent() and clamps at zero - calling it on an unindented logger is a no-op:

build := clog.With().Depth(3).Logger()

// Step back one level for a less-nested sub-logger.
back := build.With().Dedent().Logger()
back.Info().Msg("one step back")
// INF ℹ️     one step back  (depth 2, not 3)

// Indent and Dedent cancel out.
same := clog.With().Indent().Dedent().Logger()
same.Info().Msg("no change")
// INF ℹ️ no change

Dedent() is also available on animation builders:

clog.Spinner("loading").Indent().Indent().Dedent(). // net depth 1
    Wait(ctx, work).Msg("done")

Depth

Use Depth(n) to add multiple indent levels at once:

sub := clog.With().Depth(3).Logger()
sub.Info().Msg("Deeply nested")
// INF ℹ️       Deeply nested

Indent Width

The default indent width is 2 spaces per level. Change it with SetIndentWidth:

clog.SetIndentWidth(4)

Indent Prefixes

Add decorations before the message at each indent level with SetIndentPrefixes. Prefixes cycle through the slice and a separator (default " ") is appended automatically:

clog.SetIndentPrefixes([]string{"│"})

sub := clog.With().Indent().Logger()
sub.Info().Msg("hello")
// INF ℹ️   │ hello

With multiple prefixes they cycle per depth:

clog.SetIndentPrefixes([]string{"├─", "└─"})

d1 := clog.With().Indent().Logger()
d1.Info().Msg("first")
// INF ℹ️   ├─ first

d2 := clog.With().Depth(2).Logger()
d2.Info().Msg("second")
// INF ℹ️     └─ second

d3 := clog.With().Depth(3).Logger()
d3.Info().Msg("third")  // wraps back to first prefix
// INF ℹ️       ├─ third

Prefix Separator

Change the separator between the prefix and message with SetIndentPrefixSeparator:

clog.SetIndentPrefixSeparator("")   // no space
clog.SetIndentPrefixSeparator("  ") // double space

Handlers

Custom handlers receive the indent level via Entry.Indent:

clog.SetHandler(clog.HandlerFunc(func(e clog.Entry) {
    fmt.Printf("indent=%d msg=%s\n", e.Indent, e.Message)
}))

Tree Indentation

Draw tree-like structures with box-drawing connectors (├──, └──, │). Each call to Tree() adds one nesting level, and ancestor continuation lines are handled automatically.

Basic Usage

Use Tree() on a context builder with TreeFirst, TreeMiddle, or TreeLast:

clog.Info().Msg("Project")

src := clog.With().Tree(clog.TreeMiddle).Logger()
src.Info().Msg("src/")

main := src.With().Tree(clog.TreeMiddle).Logger()
main.Info().Msg("main.go")

util := src.With().Tree(clog.TreeLast).Logger()
util.Info().Msg("util.go")

mod := clog.With().Tree(clog.TreeLast).Logger()
mod.Info().Msg("go.mod")

INF ℹ️ Project
INF ℹ️ ├── src/
INF ℹ️ │   ├── main.go
INF ℹ️ │   └── util.go
INF ℹ️ └── go.mod

Positions

TreeFirst and TreeMiddle render identically by default but can be distinguished with custom characters (see below).

Combining with Indent

Tree and indent are orthogonal. When both are present, indent spaces render first, then tree connectors:

sub := clog.With().Indent().Tree(clog.TreeMiddle).Logger()
sub.Info().Msg("hello")
// INF ℹ️   ├── hello

Custom Characters

Override the default box-drawing characters with SetTreeChars:

clog.SetTreeChars(clog.TreeChars{
    First:    "┌─ ",
    Middle:   "├─ ",
    Last:     "└─ ",
    Continue: "│  ",
    Blank:    "   ",
})

Defaults include trailing whitespace for alignment (see DefaultTreeChars()).

Animations

Tree positions work on animation builders too:

clog.Spinner("loading").Tree(clog.TreeMiddle).Wait(ctx, work).Msg("done")

Handlers

Custom handlers receive the tree positions via Entry.Tree:

clog.SetHandler(clog.HandlerFunc(func(e clog.Entry) {
    fmt.Printf("tree=%v msg=%s\n", e.Tree, e.Message)
}))

Dividers

Print horizontal rules to visually separate sections of CLI output:

clog.Divider().Send()
// ────────────────────────────────────────────────────────────────────────────────

Title

Add a title to label the section:

clog.Divider().Msg("Build Phase")
// ─── Build Phase ────────────────────────────────────────────────────────────────

Custom Character

Change the line character:

clog.Divider().Char('═').Send()
// ════════════════════════════════════════════════════════════════════════════════

clog.Divider().Char('═').Msg("Deployment")
// ═══ Deployment ═════════════════════════════════════════════════════════════════

Title Alignment

Control where the title sits within the line:

// Left-aligned (default)
clog.Divider().Msg("Left")
// ─── Left ───────────────────────────────────────────────────────────────────────

// Centered
clog.Divider().Align(clog.AlignCenter).Msg("Center")
// ───────────────────────────────── Center ───────────────────────────────────────

// Right-aligned
clog.Divider().Align(clog.AlignRight).Msg("Right")
// ────────────────────────────────────────────────────────────────────── Right ───

Width

The divider fills the full terminal width. When the terminal width cannot be detected (non-TTY output, piped commands), it defaults to 80 columns.

Override the width manually with Width:

clog.Divider().Width(40).Send()
// ────────────────────────────────────────

clog.Divider().Width(40).Msg("Short")
// ─── Short ──────────────────────────────

Styling

Divider styles are configured through the Styles struct:

clog.SetStyles(&style.Config{
  DividerLine:  new(lipgloss.NewStyle().Foreground(lipgloss.Color("4"))),          // blue line
  DividerTitle: new(lipgloss.NewStyle().Bold(true).Foreground(lipgloss.Color("3"))), // bold yellow title
})

Spinner

Display animated spinners during long-running operations:

err := clog.Spinner("Downloading").
  Str("url", fileURL).
  Wait(ctx, func(ctx context.Context) error {
    return download(ctx, fileURL)
  }).
  Msg("Downloaded")

The spinner animates with moon phase emojis (🌘🌗🌖🌕🌔🌓🌒🌑) while the action runs, then logs the result. This is the default configuration (spinner.DefaultConfig), which is used when no spinner.WithConfig option is passed.

Dynamic Status Updates

Use Progress to update the spinner message, fields, and symbol during execution:

err := clog.Spinner("Processing").
  Progress(ctx, func(ctx context.Context, update *clog.Update) error {
    for i, item := range items {
      update.Msg("Processing").Str("progress", fmt.Sprintf("%d/%d", i+1, len(items))).Send()
      if err := process(ctx, item); err != nil {
        return err
      }
    }
    return nil
  }).
  Msg("Processed all items")

SetSymbol changes the icon beside the message mid-task:

update.SetSymbol("📡").Msg("Connecting").Send()

SetLevel overrides the log level on the final done line:

update.SetLevel(clog.LevelError).SetSymbol("❌").Msg("Failed").Send()

WaitResult Finalisers

.Err() is equivalent to calling .Send() with default settings (no OnSuccess/OnError overrides).

All finalisers return the error from the action. You can chain any field method (.Str(), .Int(), .Bool(), .Duration(), etc.) and .Symbol() on a WaitResult before finalising.

Custom Success/Error Behaviour

Use OnSuccessLevel, OnSuccessMessage, OnErrorLevel, and OnErrorMessage to customise how the result is logged, then call .Send():

// Fatal on error instead of the default error level
err := clog.Spinner("Connecting to database").
  Str("host", "db.internal").
  Wait(ctx, connectToDB).
  OnErrorLevel(clog.LevelFatal).
  Send()

When OnErrorMessage is set, the custom message becomes the log message and the original error is included as an error= field. Without it, the error string is used directly as the message with no extra field.

Animated Symbol on Other Animations

The spinner symbol animation can be composed with any animation type using .Spinner(). This cycles the spinner frames in the symbol slot independently of the main animation:

// Progress bar with a spinning symbol instead of a static icon
clog.Bar("Cloning", 100, opts...).
  Spinner().
  Progress(ctx, task).
  Msg("Cloned")

// Pulse with spinning symbol
clog.Pulse("Syncing").
  Spinner().
  Wait(ctx, sync).
  Msg("Synced")

// Custom spinner style on a bar
clog.Bar("Downloading", total).
  Spinner(spinner.WithConfig(spinner.Dots)).
  Progress(ctx, task).
  Msg("Downloaded")

.Spinner() with no arguments uses the default spinner style (moon phases). Pass spinner.Option values to customise:

The spinner animation is driven by wall-clock time, so it continues to animate even when the bar progress is stalled or the pulse/shimmer effect is slow.

When both .Symbol() and .Spinner() are called, .Spinner() takes precedence - the animated symbol is shown during animation, and the static symbol is used for the initial (not-started) and done states.

Default Spinner Style

Set the default spinner style for all spinners on a logger:

clog.SetSpinnerDefaults(spinner.WithConfig(spinner.Dots))

Individual spinners can still override the default with spinner.WithConfig.

Custom Spinner Style

clog.Spinner("Loading", spinner.WithConfig(spinner.Dot)).
  Wait(ctx, action).
  Msg("Done")

See fx/spinner/presets.go for the full list of available spinner types.

Individual style properties can be overridden without replacing the entire style:

// Custom frames with a slower tick
clog.Spinner("Loading",
  spinner.WithFrames("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"),
  spinner.WithInterval(120*time.Millisecond),
).
  Wait(ctx, action).
  Msg("Done")

Hyperlink Fields on Animations

Animations support the same clickable hyperlink field methods as events:

clog.Spinner("Building").
  Path("dir", "src/").
  Line("config", "config.yaml", 42).
  Column("loc", "main.go", 10, 5).
  URL("docs", "https://example.com").
  Link("help", "https://example.com", "docs").
  Wait(ctx, action).
  Msg("Built")

Elapsed Timer

Add a live elapsed-time field to any animation with .Elapsed(key):

err := clog.Spinner("Processing batch").
  Str("batch", "1/3").
  Elapsed("elapsed").
  Int("workers", 4).
  Wait(ctx, processBatch).
  Msg("Batch processed")
// INF ✅ Batch processed batch=1/3 elapsed=2s workers=4

The elapsed field respects its position relative to other field methods - it appears between batch and workers in the output above because .Elapsed("elapsed") was called between .Str() and .Int().

The display format uses the logger’s FieldFormats: ElapsedPrecision (default 0 decimal places), rounding to ElapsedRound (default 1s), hiding values below ElapsedMinimum (default 1s), and can be fully overridden with ElapsedFormat. Durations >= 1m use composite format (e.g. “1m30s”, “2h15m”).

.Elapsed(key) also accepts elapsed.Option values to override the gradient max, stops, or transition mode for this animation’s field only - see Per-Field Overrides:

err := clog.Spinner("Processing batch").
  Elapsed("elapsed", elapsed.WithGradientMax(10*time.Second)).
  Wait(ctx, processBatch).
  Msg("Batch processed")

Fields added at runtime via a live update (see Dynamic Status Updates) always render after the builder’s base fields, so a runtime-added field would normally appear after the elapsed timer. Pass elapsed.Trailing() to pin the elapsed field to the end of the row regardless:

err := clog.Spinner("Deploying").
  Str("env", "production").
  Elapsed("elapsed", elapsed.Trailing()).
  Progress(ctx, func(ctx context.Context, update *clog.Update) error {
    update.Str("tag", "v1.2.3").Send() // runtime-added field
    return deploy(ctx)
  }).
  Msg("Deployed")
// INF ✅ Deployed env=production tag=v1.2.3 elapsed=2s

Per-Event Parts Override

Override the part order for a spinner and its completion message without mutating the logger:

err := clog.Spinner("Indexing files").
  Parts(clog.PartSymbol, clog.PartMessage).
  Wait(ctx, indexFiles).
  Msg("Indexed")
// ✅ Indexed   (no level label or fields)

When set on animations, the override applies to both the animation rendering and the default completion message. You can further override on the WaitResult if the completion needs different parts:

clog.Spinner("Syncing").
  Parts(clog.PartMessage).          // animation: message only
  Wait(ctx, sync).
  Parts(clog.PartLevel, clog.PartMessage).  // completion: add level back
  Msg("Synced")

Non-TTY Silent

By default, animations print a static status line on non-TTY writers (CI, piped output) so the user knows something is in progress. Use NonTTYSilent to suppress this line entirely - the task still runs, only the output is hidden:

err := clog.Spinner("Reticulating splines").
  NonTTYSilent(true).
  Wait(ctx, reticulateSplines).
  Msg("Splines reticulated")

On a terminal, the spinner animates normally. When piped, no output is produced until the completion message.

This is useful for decorative animations that add noise in CI logs. For level-based suppression across all animations, see SetNonTTYLevel.

NonTTYSilent works with all animation types: spinners, bars, pulses, shimmers, and groups.

Delayed Animation

Use .After(d) to suppress the animation for an initial duration. If the task finishes before the delay, no animation is shown at all - useful for operations that are usually fast but occasionally slow:

err := clog.Spinner("Fetching config").
  After(time.Second).
  Wait(ctx, fetchConfig).
  Msg("Config loaded")

If fetchConfig completes in under 1 second, the user sees nothing until the final “Config loaded” message. If it takes longer, the spinner appears after 1 second.

Bar

Bar creates a determinate progress bar that shows filled/empty cells and a live percentage. Use SetProgress on the Update to advance the bar.

err := clog.Bar("Downloading", 100).
  Str("file", "release.tar.gz").
  Elapsed("elapsed").
  Progress(ctx, func(ctx context.Context, p *clog.Update) error {
    for i := range 101 {
      p.SetProgress(i).Msg("Downloading").Send()
      time.Sleep(20 * time.Millisecond)
    }
    return nil
  }).
  Symbol("✅").
  Msg("Download complete")
// INF ⏳ Downloading ━━━━━━━━━╸╺━━━━━━━━━━━ 42% elapsed=1.2s
// INF ✅ Download complete file=release.tar.gz elapsed=3.4s

SetTotal can be called mid-task to update the denominator if the total becomes known after the task starts:

p.SetProgress(50).SetTotal(200).Msg("Processing").Send()
p.Msgf("Processing %d/%d", current, total).Send()

AddTotal atomically adds to the total - useful for “discovered more work” patterns where the full scope isn’t known upfront:

p.AddTotal(50)  // discovered 50 more items
p.AddTotal(-10) // 10 items turned out to be duplicates

SetSymbol changes the icon displayed beside the message during animation. This is useful for showing different phases of a multi-stage task:

p.SetSymbol("📡").SetProgress(i).Str("stage", "receiving").Send()
p.SetSymbol("🔍").SetProgress(i).Str("stage", "resolving").Send()

SetLevel overrides the log level shown on the final done line. This is useful when a task fails and you want the completed line to render at error level:

p.SetSymbol("❌").SetLevel(clog.LevelError).Msg("Failed").Send()

Animated Symbol

By default, bars show a static symbol (⏳). Use .Spinner() to replace it with a spinning animation that cycles independently of the bar progress:

clog.Bar("Cloning", 100, opts...).
  Spinner().
  Progress(ctx, task).
  Msg("Cloned")

// With a custom spinner style
clog.Bar("Downloading", total).
  Spinner(spinner.WithConfig(spinner.Dots)).
  Progress(ctx, task).
  Msg("Downloaded")

With no arguments, .Spinner() uses the default spinner style (moon phases). Pass spinner.Option values to customise the frames, interval, or playback direction. See Spinner for the full list of options and presets.

The spinner animation is driven by wall-clock time, so it keeps animating even when the bar progress is stalled.

Pending Mode

If you don’t want zero-progress tasks to show an empty bar, use PendingHide:

clog.Bar("Cloning", 1, bar.WithPendingMode(bar.PendingHide))

This suppresses the entire bar block, including widgets, until progress becomes positive.

By default, the bar fill uses exponential smoothing (SmoothEase) so that large jumps in progress animate smoothly instead of snapping. Disable it with SmoothNone, or tune the time constant with WithSmoothingTau (default 120ms - smaller is snappier, larger is smoother):

clog.Bar("Uploading", total, bar.WithSmoothingMode(bar.SmoothNone))
clog.Bar("Uploading", total, bar.WithSmoothingTau(100*time.Millisecond))

If frequent updates make ETA or rate text too jumpy, coalesce timing-derived widget and dynamic-field updates:

clog.Bar("Cloning", 1, bar.WithUpdateInterval(time.Second))

This rate-limits timing-derived text such as ETA, rate, and elapsed while leaving the bar fill, percent/current-total text, message, symbol, and other live updates responsive.

Styles

Seven pre-built styles are available in fx/bar/presets.go. Pass any of them via bar.WithConfig():

clog.Bar("Uploading", total, bar.WithConfig(bar.Smooth)).
  Progress(ctx, task).
  Msg("Done")

bar.Thin and bar.Smooth use half-cell resolution via HalfFilled (and HalfEmpty for bar.Thin), giving twice the visual granularity of full-cell styles. bar.Gradient and bar.Braille use GradientFill for 8x sub-cell resolution - the smoothest built-in options. bar.Braille is inspired by Docker Compose’s progress display, using braille dot characters that progressively fill from bottom to top.

Custom Style

Build a fully custom configuration by passing a bar.WithConfig() option:

import "github.com/gechr/clog/fx/bar/widget"

clog.Bar("Uploading", total, bar.WithConfig(bar.Config{
    Placement:   bar.PlaceInline, // inline with message (default: bar.PlaceRightPad)

    CapStyle:    new(lipgloss.NewStyle().Bold(true)), // style for [ ] caps (default: bold white)
    CapLeft:     "|",
    CapRight:    "|",

    CharEmpty:   '-',
    CharFill:    '=',
    CharHead:    '>', // decorative head at leading edge (0 = disabled)

    HalfEmpty:   0, // half-cell trailing edge for 2x resolution (0 = disabled)
    HalfFilled:  0, // half-cell leading edge for 2x resolution (0 = disabled)

    Separator:   " ", // separator between message, bar, and widget text

    StyleEmpty:  new(lipgloss.NewStyle().Foreground(lipgloss.Color("8"))),  // grey
    StyleFill:   new(lipgloss.NewStyle().Foreground(lipgloss.Color("2"))),  // green

    WidgetLeft:  widget.Percent(widget.WithDigits(1)), // "50.0%" to the left of the bar
    WidgetRight: widget.None(), // suppress the default right-side percent

    Width:       30, // fixed inner width (0 = auto-size from terminal)
    WidthMin:    10, // auto-size minimum (default 10)
    WidthMax:    40, // auto-size maximum (default 40)
  })).
  Progress(ctx, task).
  Msg("Done")

When Width is 0, the bar auto-sizes to one quarter of the terminal width, clamped to [WidthMin, WidthMax].

Any field can be overridden via option functions without building a full custom style:

clog.Bar("Downloading", 100, bar.WithConfig(bar.Braille), bar.WithWidth(30))

Structure

Characters

Width

Colors

Widgets

All presets use bold white CapStyle. Pass bar.WithCapStyle(lipgloss.NewStyle()) for unstyled caps.

Progress Gradient

Color the bar fill based on progress using ProgressGradient. The filled portion shifts through the gradient as progress advances (e.g. red at 0%, yellow at 50%, green at 100%):

style := bar.Block
style.ProgressGradient = bar.DefaultGradient() // red → yellow → green

clog.Bar("Building", 100, bar.WithConfig(style)).
  Progress(ctx, task).
  Msg("Built")

Custom gradients work the same as other gradient fields:

style.ProgressGradient = []style.ColorStop{
  {Position: 0, Color: colorful.Color{R: 0.3, G: 0.3, B: 1}},   // blue
  {Position: 0.5, Color: colorful.Color{R: 1, G: 1, B: 1}},     // white
  {Position: 1, Color: colorful.Color{R: 0.3, G: 1, B: 0.3}},   // green
}

When set, ProgressGradient overrides the StyleFill foreground color. Use bar.DefaultGradient() to get the default red → yellow → green stops.

Alignment

The Placement field on bar.Config controls where the bar appears on the line:

The padded variants (bar.PlaceRightPad, bar.PlaceLeftPad) fill the gap between message and bar with spaces to span the terminal width. When the terminal is too narrow, they fall back to the Separator between parts.

bar.PlaceAligned dynamically calculates the longest message in a group and aligns all bars to the same starting column. For standalone (non-group) bars, it falls back to bar.PlaceRight.

Widgets

WidgetLeft and WidgetRight on bar.Config control text annotations beside the bar. Each is a bar.Widget - a callback that receives progress state and returns a string:

type bar.State struct {
  Current int
  Total   int
  Elapsed time.Duration
  Rate    float64 // items per second
}
type bar.Widget func(bar.State) string

All presets set WidgetRight: widget.Percent() - padded percentage on the right (e.g. " 42%"). When both widgets are nil, the same default applies.

Built-in widgets:

All widget constructors accept widget.Option values:

Composing multiple widgets:

Use widget.Widgets to combine several widgets on a single side. Empty outputs are filtered and the rest are joined with a space:

style := bar.Thin
style.WidgetRight = widget.Widgets(widget.ETA(), widget.Rate())
// INF ⏳ Processing ━━━━━━━╸╺━━━━━━━━━━ ETA 2m30s 150/s

Add a visual divider with widget.Separator:

style.WidgetRight = widget.Widgets(
  widget.ETA(),
  widget.Separator("│"),
  widget.Rate(),
)
// INF ⏳ Processing ━━━━━━━╸╺━━━━━━━━━━ ETA 2m30s │ 150/s

Pass widget.WithStyle to any widget to apply a Lipgloss style to its output:

faint := lipgloss.NewStyle().Faint(true)
style.WidgetRight = widget.Widgets(
  widget.ETA(widget.WithStyle(faint)),
  widget.Separator("│", widget.WithStyle(faint)),
  widget.Rate(widget.WithStyle(faint)),
)
// INF ⏳ Processing ━━━━━━━╸╺━━━━━━━━━━ ETA 2m30s │ 150/s  (all rendered faint)

Pass widget.WithProgressGradient to color the percent text based on progress, matching the bar’s gradient:

style := bar.Smooth
style.ProgressGradient = bar.DefaultGradient()
style.WidgetLeft = widget.Percent(widget.WithProgressGradient(bar.DefaultGradient()...))
style.WidgetRight = widget.None()
// INF ⏳ Uploading │████▌     │  50%  (percent colored red→yellow→green by progress)

Move percent to the left:

style := bar.Thin
style.WidgetLeft = widget.Percent()
style.WidgetRight = widget.None()

Download progress with byte sizes:

fileSize := 150 * 1000 * 1000 // 150 MB
style := bar.Smooth
style.WidgetRight = widget.Bytes()

clog.Bar("Downloading", fileSize, bar.WithConfig(style)).
  Str("file", "model.bin").
  Progress(ctx, func(ctx context.Context, p *clog.Update) error {
    // p.SetProgress(bytesReceived).Send()
  }).
  Msg("Downloaded")
// INF ⏳ Downloading │████▌     │  75 MB / 150 MB file=model.bin

The current value is right-aligned to the total’s width to prevent the bar from jumping as digits change. Use widget.IBytes() for base-1024 units (KiB, MiB, GiB).

ETA and rate:

style := bar.Block
style.WidgetLeft = widget.ETA()
style.WidgetRight = widget.Rate(widget.WithUnit("items"))

clog.Bar("Processing", 500, bar.WithConfig(style)).
  Progress(ctx, task).
  Msg("Done")
// INF ⏳ Processing ETA 2m30s │█████░░░░░│ 150 items/s

widget.ETA shows "ETA ∞" before any progress, a countdown during the task, and "" when complete. widget.Rate accepts an optional widget.WithUnit for a label; without it, output is "150/s".

Byte throughput:

style := bar.Gradient
style.WidgetRight = widget.BytesRate()

clog.Bar("Uploading", totalBytes, bar.WithConfig(style)).
  Progress(ctx, task).
  Msg("Done")
// INF ⏳ Uploading │██████▍   │ 82.9 MB/s

Use widget.IBytesRate() for IEC units (MiB/s). Both accept widget.WithDigits(n) to control significant digits (default 3).

Custom widget:

style := bar.Thin
style.WidgetRight = func(s bar.State) string {
  remaining := s.Total - s.Current
  return fmt.Sprintf("%d remaining", remaining)
}

Suppress percent entirely:

style := bar.Thin
style.WidgetRight = widget.None()

Percentage as a Field

Use .BarPercent(key) on the builder to move the percentage into structured fields. This suppresses the default right-side widget:

clog.Bar("Installing", 100).
  BarPercent("progress").
  Elapsed("elapsed").
  Progress(ctx, task).
  Msg("Installed")
// INF ⏳ Installing          ━━━━━━━╸╺━━━━━━━━━━ progress=45% elapsed=1.2s

All animations gracefully degrade: when colors are disabled (CI, piped output), a static status line with an ⏳ symbol is printed instead.

The icon displayed during Pulse, Shimmer, and Bar animations defaults to ⏳ and can be changed with .Symbol() on the builder (before the task starts) or SetSymbol() on the Update (during the task):

clog.Pulse("Warming up").
  Symbol("🔄").
  Wait(ctx, action).
  Msg("Ready")

Shimmer

Shimmer creates an independent animation where each character is colored based on its position in a sweeping gradient wave.

// Default gradient
clog.Shimmer("Indexing documents").
  Wait(ctx, action).
  Msg("Indexed")

// Custom gradient with direction
clog.Shimmer("Synchronizing",
  shimmer.WithGradient(
    style.ColorStop{Position: 0, Color: colorful.Color{R: 0.3, G: 0.3, B: 0.8}},
    style.ColorStop{Position: 0.5, Color: colorful.Color{R: 1, G: 1, B: 1}},
    style.ColorStop{Position: 1, Color: colorful.Color{R: 0.3, G: 0.3, B: 0.8}},
  ),
  shimmer.WithDirection(shimmer.MiddleIn),
).
  Wait(ctx, action).
  Msg("Synchronized")

Use shimmer.DefaultGradient() to get the default gradient stops.

Directions

Speed

Control how fast the animation cycles with shimmer.WithSpeed(cyclesPerSecond). The default is 0.5 (one full cycle every two seconds). Values ≤ 0 are treated as the default.

clog.Shimmer("Fast shimmer",
  shimmer.WithSpeed(2.0),  // 2 gradient cycles per second
).
  Wait(ctx, action).
  Msg("Done")

clog.Pulse("Quick pulse", pulse.WithSpeed(1.5)).
  Wait(ctx, action).
  Msg("Done")

Both pulse and shimmer use ColorStop for gradient definitions:

type ColorStop struct {
  Position float64        // 0.0-1.0
  Color    colorful.Color // from github.com/lucasb-eyer/go-colorful
}

Pulse

Pulse creates an independent animation where all characters in the message fade uniformly between gradient colors.

// Default gradient (blue-gray to cyan)
clog.Pulse("Warming up").
  Wait(ctx, action).
  Msg("Ready")

// Custom gradient
clog.Pulse("Replicating",
  pulse.WithGradient(
    style.ColorStop{Position: 0, Color: colorful.Color{R: 1, G: 0.2, B: 0.2}},
    style.ColorStop{Position: 0.5, Color: colorful.Color{R: 1, G: 1, B: 0.3}},
    style.ColorStop{Position: 1, Color: colorful.Color{R: 1, G: 0.2, B: 0.2}},
  ),
).
  Wait(ctx, action).
  Msg("Replicated")

// Custom speed (2× faster)
clog.Pulse("Processing",
  pulse.WithSpeed(1.0),
).
  Wait(ctx, action).
  Msg("Done")

Use pulse.DefaultConfig() to inspect the default configuration, or pulse.DefaultGradient() to get just the default gradient stops.

Group

Group runs multiple animations concurrently in a multi-line block, redrawn in place each tick (frames are skipped when nothing changed, and repaints use synchronized output on terminals that support it).

g := clog.Group(ctx)
g.Add(clog.Spinner("Processing data").Int("workers", 4)).
  Run(func(ctx context.Context) error {
    return processData(ctx)
  })
g.Add(clog.Bar("Downloading", 100)).
  Progress(func(ctx context.Context, p *clog.Update) error {
    for i := range 101 {
      p.SetProgress(i).Send()
      time.Sleep(20 * time.Millisecond)
    }
    return nil
  })
g.Wait().Symbol("✅").Msg("All tasks complete")

Group options live in the fx package (github.com/gechr/clog/fx). To align the first field column across rows, enable group field alignment:

g := clog.Group(ctx, fx.WithFieldAlignment(fx.FieldAlignmentMessage))

To let clog limit how many tasks run at once, use WithParallelism:

g := clog.Group(ctx, fx.WithParallelism(5))

By default, all animations in a group share a common epoch so spinners, pulses, and shimmers stay in lockstep regardless of when each task starts. To let each task animate from its own start time instead, disable sync:

g := clog.Group(ctx, fx.WithoutSyncAnimations())

To keep grouped bar fills and their percentage text from visibly moving backward when task totals grow or progress is reported in phases, enable monotonic mode:

g := clog.Group(ctx, fx.WithMonotonic())

When the context is cancelled (e.g. on SIGINT), the last rendered frame is preserved so the user can see what was on screen. To clear the block instead, use WithClearOnCancel:

g := clog.Group(ctx, fx.WithClearOnCancel())

To hide completed tasks from the rendered block so only active and pending tasks remain visible, use WithHideDone:

g := clog.Group(ctx, fx.WithHideDone())

To add a header or footer status line that updates each tick, use WithHeader or WithFooter. Pass a builder for the initial config (level, symbol, parts) and a callback that updates the message and fields each tick:

g := clog.Group(ctx,
  fx.WithHideDone(),
  fx.WithFooter(
    clog.Spinner("Cloned"),
    func(done, total int, u *clog.Update) {
      u.Msg("Cloned").Str("progress", fmt.Sprintf("%d/%d", done, total)).Send()
    },
  ),
)

While the tasks run, the terminal shows all animations updating simultaneously:

INF 🌒 Processing data workers=4
INF ⏳ Downloading ━━━━━━━━━╸╺━━━━━━━━━━━ 42%

When all tasks finish, the block is cleared and a single summary line is logged. Alternatively, use per-task results for individual completion messages:

g := clog.Group(ctx)
proc := g.Add(clog.Spinner("Processing")).Run(processData)
dl := g.Add(clog.Bar("Downloading", 100)).Progress(download)
g.Wait()
proc.Symbol("✅").Msg("Processing done")
dl.Symbol("✅").Msg("Download complete")

Any mix of animation types works: spinners, bars, pulses, and shimmers can all run in the same group.

API

FieldAlignmentMessage applies when PartFields comes immediately after PartMessage in the part order, which is the default layout.

WithFooter(b, fn) and WithHeader(b, fn) take a *fx.Builder for initial config (level, symbol, parts) and a GroupStatusFunc callback func(done, total int, u *Update) called each render tick. The callback uses the Update to set the message and fields. Header and footer lines count towards the terminal height cap.

WithHideDone() removes completed tasks from the rendered block so only active and pending tasks are visible. Bar alignment layout only considers visible tasks.

WithMaxHeightPercent(percent) caps the group block to a fraction of the terminal height (e.g. 0.5 for half). Clamped to (0, 1]. When both WithMaxLines and WithMaxHeightPercent are set, the smaller wins.

WithMaxLines(n) caps the visible lines in the group block. When set, this takes precedence over the automatic terminal height cap. Header and footer lines count towards this limit. Values less than or equal to zero are ignored.

WithMonotonic() clamps the rendered bar fill, percentage text, and widget values to the highest fraction seen so far. It does not change the underlying task progress values.

WithParallelism(n) removes the limit when n <= 0.

Animation sync (the default) records a shared epoch when the render loop starts. Spinner frame indices, pulse sine phase, and shimmer scroll phase are all derived from this epoch instead of each task’s individual start time, so animations stay in lockstep. Elapsed-time fields remain per-task and freeze at each task’s finish time, so a completed line reports the task’s actual runtime while its siblings continue. WithoutSyncAnimations() disables this and lets each task animate from its own start time.

GroupResult and TaskResult support the same chaining as WaitResult: .Msg(), .Parts(), .Symbol(), .Send(), .Err(), .Silent(), .OnErrorLevel(), .OnErrorMessage(), .OnSuccessLevel(), .OnSuccessMessage(), and all field methods (.Str(), .Int(), etc.).

Per-Event Parts Override

Override the part order for individual animations and their completion messages:

g := clog.Group(ctx)

// Animation + completion both use overridden parts.
proc := g.Add(clog.Spinner("Processing").Parts(clog.PartMessage)).
  Run(processData)

dl := g.Add(clog.Bar("Downloading", 100)).
  Progress(download)

// Override parts only on the summary line.
g.Wait().Parts(clog.PartSymbol, clog.PartMessage).Msg("All done")

.Parts() on the animation propagates to the TaskResult. Call .Parts() on TaskResult or GroupResult to override independently for the completion message.

GroupResult.Err() / .Silent() returns the errors.Join of all task errors (nil when all succeeded).

Printer

Output styled data directly without a log level, key, or message:

clog.Print().RawJSON([]byte(`{"status":"ok","count":42,"active":true}`))
// {
//   "status": "ok",
//   "count": 42,
//   "active": true
// }

The Printer writes directly to the logger’s output, bypassing any custom Handler. It uses the logger’s style configurations for token colors.

JSON

JSON marshals any Go value; RawJSON accepts pre-serialized bytes:

clog.Print().JSON(userStruct)
clog.Print().RawJSON(responseBody)

Print Mode

The default mode is JSONPretty, which pretty-prints with indentation. Set the global default with SetJSONPrintMode, or override per-call with Mode:

// Global default: flatten to single line
clog.SetJSONPrintMode(clog.JSONFlat)

// Per-call override
clog.Print().Mode(clog.JSONPretty).RawJSON(data)
clog.Print().Mode(clog.JSONFlat).RawJSON(data)

Styling

Printer JSON inherits token colors (keys, strings, numbers, etc.) from the logger’s JSON styles. Field-specific rendering modes (JSONModeHuman, JSONModeFlat) are not applied – the Printer always uses standard JSON rendering.

custom := style.DefaultJSON()
custom.Key = new(lipgloss.NewStyle().Foreground(lipgloss.Color("#50fa7b")))
clog.SetStyles(&style.Config{JSON: custom})

YAML

YAML marshals any Go value; RawYAML accepts pre-serialized bytes:

clog.Print().YAML(configStruct)
clog.Print().RawYAML(responseBody)

See YAML for styling options.

TOML

TOML marshals any Go value; RawTOML accepts pre-serialized bytes:

clog.Print().TOML(configStruct)
clog.Print().RawTOML(configBytes)

See TOML for styling options.

HCL

RawHCL accepts pre-serialized HCL bytes (there is no marshal method since HCL has no standard Go marshal API):

clog.Print().RawHCL(terraformConfig)

See HCL for styling options.

Themes

Printer styles default to terminal-aware light/dark selection: on the first colored write the logger detects the background of its own output and picks a matching theme (dark mode preserves the original Dracula-based colors). The terminal is queried at most once, and never for non-terminal or color-disabled outputs, which use the dark theme. Switch all four format styles at once with SetTheme, which takes a light/dark pair:

clog.SetTheme(theme.MustPair(theme.CatppuccinLatte(), theme.Dracula()))

For a fixed theme regardless of the terminal background, wrap it with theme.Single:

clog.SetTheme(theme.Single(theme.Monokai()))

Per-token overrides still work after setting a theme:

clog.SetTheme(theme.Single(theme.Monokai()))
s := clog.DefaultStyles()
s.JSON.Key = new(lipgloss.NewStyle().Foreground(lipgloss.Color("#ff0000")))
clog.SetStyles(s)

To build styles from a theme directly:

custom := style.NewJSON(theme.Monokai())

Environment variables

The default logger reads its theme from the environment (highest precedence first):

1. CLOG_THEME - an explicit theme, applied on both backgrounds (via theme.Single):

   CLOG_THEME=monokai
   

2. CLOG_THEME_LIGHT and CLOG_THEME_DARK - a light/dark pair; the entry matching the terminal background is selected on the first write:

   CLOG_THEME_LIGHT=catppuccin-latte
   CLOG_THEME_DARK=dracula
   

CLOG_THEME takes precedence over the light/dark pair when both are set. With a custom prefix (see SetEnvPrefix), <PREFIX>_THEME* is checked first, then the CLOG_* fallback.

The same pair can also be loaded programmatically:

themes, err := theme.PairFromEnv()
if err != nil {
    return err
}
clog.SetTheme(themes)

Available themes:

• theme.Dark()
• theme.Light()
• theme.CatppuccinFrappe()
• theme.CatppuccinLatte()
• theme.CatppuccinMacchiato()
• theme.CatppuccinMocha()
• theme.Dracula()
• theme.Monokai()

Indentation

The default indent is two spaces. SetPrintIndent sets the baseline for all formats; SetJSONIndent and SetYAMLIndent override it for a specific format:

clog.SetPrintIndent("\t")       // tabs for both JSON and YAML
clog.SetJSONIndent("    ")      // 4 spaces for JSON only
clog.SetYAMLIndent("  ")        // 2 spaces for YAML only

YAML sequences are indented under their parent key by default. Disable with SetYAMLIndentSequence(false).

Sub-loggers

Each logger has its own Printer, so sub-loggers with different styles produce different output:

logger := clog.NewWriter(os.Stdout)
logger.SetStyles(&style.Config{
    JSON: style.DefaultJSON().WithSpacing(style.JSONSpacingAll),
})

logger.Print().RawJSON(data)

JSON

JSON marshals any Go value to JSON; RawJSON accepts pre-serialized bytes. Both emit the result with syntax highlighting.

// Marshal a Go value
clog.Info().JSON("user", userStruct).Msg("ok")
clog.Info().JSON("config", map[string]any{"port": 8080, "debug": true}).Msg("started")

// Pre-serialized bytes (no marshal overhead)
clog.Error().
  Str("batch", "1/1").
  RawJSON("error", []byte(`{"status":"unprocessable_entity","detail":"validation failed","code":null}`)).
  Msg("Batch failed")
// ERR ❌ Batch failed batch=1/1 error={"status":"unprocessable_entity","detail":"validation failed","code":null}

Use JSON when you have a Go value to log; use RawJSON when you already have bytes (HTTP response bodies, json.RawMessage, database JSON columns) to avoid an unnecessary marshal/unmarshal round-trip. JSON logs the error string as the field value if marshalling fails.

Pretty-printed JSON is automatically flattened to a single line. Highlighting uses a Dracula-inspired color scheme by default (space after commas included). Disable or customise it via JSON in Styles:

// Custom colors
custom := style.DefaultJSON()
custom.Key = new(lipgloss.NewStyle().Foreground(lipgloss.Color("#50fa7b")))
clog.SetStyles(&style.Config{JSON: custom})

// Disable highlighting (reset all styles, then re-apply without JSON)
clog.SetStyles(nil) // reset to defaults

Number is the base fallback for all numeric tokens. Five sub-styles allow finer control and fall back to Number when nil:

custom := style.DefaultJSON()
custom.NumberNegative = new(lipgloss.NewStyle().Foreground(lipgloss.Color("1"))) // red
custom.NumberZero = new(lipgloss.NewStyle().Foreground(lipgloss.Color("8")))     // grey
styles.JSON = custom
clog.SetStyles(styles)

Rendering Modes

Set style.JSON.Mode to control how JSON structure is rendered:

style.JSONModeHuman - keys are unquoted unless they contain ,{}[]\s:#"' or start with ////*. String values are unquoted unless they start with a forbidden character, end with whitespace, are ambiguous as a JSON keyword (true, false, null), or look like a number. Empty strings always render as "".

styles.JSON = style.DefaultJSON()
styles.JSON.Mode = style.JSONModeHuman

clog.Info().
  RawJSON("response", []byte(`{"status":"ok","count":42,"active":true,"deleted_at":null}`)).
  Msg("Fetched")
// INF ℹ️ Fetched response={status:ok, count:42, active:true, deleted_at:null}

style.JSONModeFlat - nested objects are recursed into and their keys joined with .; arrays are kept intact as values:

styles.JSON.Mode = style.JSONModeFlat

clog.Info().
  RawJSON("resp", []byte(`{"user":{"name":"alice","role":"admin"},"tags":["a","b"]}`)).
  Msg("Auth")
// INF ℹ️ Auth resp={user.name:alice, user.role:admin, tags:[a, b]}

Spacing

style.JSON.Spacing is a bitmask controlling where spaces are inserted. The default (style.DefaultJSON) adds a space after commas.

// Fluent builder
styles.JSON = style.DefaultJSON().WithSpacing(style.JSONSpacingAll)

// Direct assignment
styles.JSON.Spacing = style.JSONSpacingAfterComma | style.JSONSpacingBeforeObject

style.JSONSpacingAfterColon and style.JSONSpacingBeforeObject/style.JSONSpacingBeforeArray are independent - combining them produces two spaces before a nested value.

Omitting Commas

Set OmitCommas: true to drop the , separator. Combine with style.JSONSpacingAfterComma to keep a space in its place:

styles.JSON.OmitCommas = true
styles.JSON.Spacing |= style.JSONSpacingAfterComma

clog.Info().
  RawJSON("r", []byte(`{"a":1,"b":2,"c":true}`)).
  Msg("ok")
// INF ℹ️ ok r={a:1 b:2 c:true}

YAML

YAML marshals any Go value; RawYAML accepts pre-serialized bytes:

clog.Print().YAML(configStruct)
clog.Print().RawYAML(responseBody)

Styling

Token colors are configured via styles:

custom := style.DefaultYAML()
custom.Key = new(lipgloss.NewStyle().Foreground(lipgloss.Color("#50fa7b")))
clog.SetStyles(&style.Config{YAML: custom})

TOML

TOML marshals any Go value; RawTOML accepts pre-serialized bytes:

clog.Print().TOML(configStruct)
clog.Print().RawTOML(configBytes)

Styling

Token colors are configured via styles:

custom := style.DefaultTOML()
custom.Key = new(lipgloss.NewStyle().Foreground(lipgloss.Color("#50fa7b")))
clog.SetStyles(&style.Config{TOML: custom})

HCL

RawHCL accepts pre-serialized HCL bytes (there is no marshal method since HCL has no standard Go marshal API):

clog.Print().RawHCL(terraformConfig)

Styling

Token colors are configured via styles:

custom := style.DefaultHCL()
custom.Key = new(lipgloss.NewStyle().Foreground(lipgloss.Color("#50fa7b")))
clog.SetStyles(&style.Config{HCL: custom})

Configuration

Default Logger

The package-level functions (Info(), Warn(), etc.) use the Default logger which writes to os.Stdout at LevelInfo.

// Full configuration
clog.Configure(&clog.Config{
  Verbose: true,                            // enables debug level + timestamps
  Output:  clog.Stderr(clog.ColorAuto),     // custom output
  Styles:  customStyles,                    // custom visual styles
})

// Toggle verbose mode
clog.SetVerbose(true)

Output

Each Logger writes to an *Output, which bundles an io.Writer with its terminal capabilities (TTY detection, width, color profile):

// Standard constructors
out := clog.Stdout(clog.ColorAuto)                  // os.Stdout with auto-detection
out := clog.Stderr(clog.ColorAlways)                // os.Stderr with forced colors
out := clog.NewOutput(w, clog.ColorNever)           // arbitrary writer, colors disabled
out := clog.TestOutput(&buf)                        // shorthand for NewOutput(w, ColorNever)

Output methods:

Custom Logger

logger := clog.New(clog.Stderr(clog.ColorAuto))
logger.SetLevel(clog.LevelDebug)
logger.SetReportTimestamp(true)
logger.SetTimeFormat("15:04:05.000")
logger.SetFieldTimeFormat(time.Kitchen)    // format for .Time() fields (default: time.RFC3339)
logger.SetTimeLocation(time.UTC)           // timezone for timestamps (default: time.Local)
logger.SetFieldStyleLevel(clog.LevelTrace) // min level for field value styling (default: clog.LevelInfo)
logger.SetNonTTYLevel(clog.LevelWarn)      // suppress below Warn on non-TTY writers
logger.SetHandler(myHandler)

For simple cases where you just need a writer with default color detection:

logger := clog.NewWriter(os.Stderr) // equivalent to New(NewOutput(os.Stderr, ColorAuto))

Field Formats

Field formatting (durations, elapsed timers, percentages, numbers, hyperlinks, quantity units) is configured per-logger via the FieldFormats struct. Start from DefaultFieldFormats(), set the fields you want, and apply with SetFieldFormats - configuration is per-Logger, so two loggers can format fields differently:

f := clog.DefaultFieldFormats()
f.PercentPrecision = 1                  // "75.0%" instead of "75%"
f.ElapsedGradientMax = 30 * time.Second // enable the elapsed gradient
f.HyperlinkLineFormat = "vscode"        // preset name, expanded on SetFieldFormats
logger.SetFieldFormats(f)

// Or configure the package-level Default logger:
clog.SetFieldFormats(f)

// Read back the current configuration:
current := logger.FieldFormats()

SetFieldFormats has replace-all semantics (like SetParts): the struct you pass replaces the logger’s entire field-format configuration, so always start from DefaultFieldFormats() (or logger.FieldFormats()) rather than a zero value.

To change a single option without the read-modify-write dance, each field has a per-field convenience setter that preserves the rest of the snapshot - e.g. logger.SetPercentPrecision(1), logger.SetElapsedGradientMax(30*time.Second), logger.SetHyperlinkFileFormat("vscode") (presets are expanded and pushed to the output automatically). These also exist as package-level functions for the Default logger (clog.SetPercentPrecision(1), etc.).

SetTimeGradientMax(max) is a shorthand that sets both DurationGradientMax and ElapsedGradientMax at once, since duration and elapsed fields usually share a gradient ceiling.

Hyperlink format fields accept either a full format string with {path}/{line}/{column} placeholders, or a named preset (e.g. "vscode"), which is expanded when SetFieldFormats is called. See Hyperlinks for details.

Number formatting

By default numbers render verbatim (1234567, 1234567/9999999). Three modes control how integer fields and both halves of a Fraction are rendered:

• NumberPlain - verbatim, e.g. 1234567 (the default).
• NumberGrouped - locale-style digit grouping, e.g. 1,234,567. The separator is configurable.
• NumberCompact - abbreviated with K/M/B/T suffixes, e.g. 1.2M. Values below NumberCompactMinimum (default 1000) render with NumberCompactFallback (grouped by default), so a series reads 9,999 → 10K → 11K rather than jumping straight from plain to abbreviated. Set NumberCompactFallback = NumberPlain to keep small values verbatim (9999).

Convenience setters avoid the read-modify-write dance for the common cases:

logger.SetNumberFormat(clog.NumberGrouped)   // applies to ints AND fractions
logger.SetNumberGroupSeparator(" ")          // "1 234 567"

logger.SetFractionFormat(clog.NumberCompact) // fractions only; ints keep NumberFormat
logger.SetNumberCompactMinimum(10_000)       // only abbreviate at >= 10,000

To combine grouping and abbreviation - grouped digits for small values, K/M/B/T suffixes for large ones - select NumberCompact and raise the minimum:

logger.SetNumberFormat(clog.NumberCompact)
logger.SetNumberCompactMinimum(10_000) // 9,999 -> 10K -> 11K -> 1.2M

SetNumberFormat is the global knob; SetFractionFormat overrides it for fractions and falls back to it when unset. A single field can override both via fraction.WithFormat:

clog.Info("progress").
    Fraction("done", 1234567, 9999999, fraction.WithFormat(clog.NumberCompact)).
    Send() // done=1.2M/10M

The separator is not locale-aware - pick the one that suits your output (",", ".", " ", "_").

Utility Functions

clog.GetLevel()                  // returns the current level of the Default logger
clog.IsVerbose()                 // true if level is Debug or Trace
clog.IsTerminal()                // true if Default output is a terminal
clog.ColorsDisabled()            // true if colors are disabled on the Default logger
clog.SetOutput(out)              // change the output (accepts *Output)
clog.SetOutputWriter(w)          // change the output writer (with ColorAuto)
clog.SetExitCode(2)              // set default Fatal exit code (default: 1)
clog.SetExitFunc(fn)             // override os.Exit for Fatal (useful in tests)
logger.Output()                  // returns the Logger's *Output

Environment Variables

All env vars follow the pattern {PREFIX}_{SUFFIX}. The default prefix is CLOG.

CLOG_LOG_LEVEL=debug ./some-app  # enables debug logging + timestamps
CLOG_LOG_LEVEL=warn ./some-app   # suppresses info messages

Custom Env Prefix

Use SetEnvPrefix to whitelabel the env var names for your application. The custom prefix is checked first, with CLOG_ as a fallback.

clog.SetEnvPrefix("MYAPP")
// Now checks MYAPP_LOG_LEVEL first, then CLOG_LOG_LEVEL
// Now checks MYAPP_HYPERLINK_PATH_FORMAT first, then CLOG_HYPERLINK_PATH_FORMAT
// etc.

This means CLOG_LOG_LEVEL=debug always works as a universal escape hatch, even when the application uses a custom prefix.

NO_COLOR is never prefixed - it follows the no-color.org standard independently.