Owl

To use Owl in your Elixir project, add it to your mix.exs dependencies.

Note on Multibyte Characters: If your application needs to support multibyte characters (such as emojis), you should also include the ucwidth dependency to ensure correct width calculations.

def deps do
  [
    {:owl, "~> 0.13"},
    # ucwidth is an optional dependency, uncomment it for multibyte characters support (emoji, etc)
    {:ucwidth, "~> 0.2"}
  ]
end

An Owl.Tag is a container for data and associated ANSI sequences. It acts like an HTML tag for the console, providing local bindings for styles.

When using raw ANSI sequences (e.g., IO.ANSI.red()), you must manually reset colors or backgrounds to prevent styles from leaking into subsequent text. Owl.Tag solves this by encapsulating the data and its styles, allowing you to nest tagged content within other tags without manual cleanup.

To create a tag, use Owl.Data.tag/2 instead of the deprecated Owl.Tag.new/2.

# Nesting tags automatically handles style cleanup
substring = Owl.Data.tag("world", :green)
Owl.IO.puts(Owl.Data.tag(["Hello ", substring, "!!"], :red))

The Owl.Daemon allows you to intercept and process the stdout/stderr of a command using the :handle_data option.

When providing :handle_data, you pass a tuple: {initial_state, callback}.

• initial_state: Any term you want to carry through the lifecycle of the daemon.
• callback: A function with the signature fn(text_lines, current_state) -> new_state end.

Every time the command produces output, the callback is executed, and the returned new_state is stored and passed back into the next call. The output is also automatically prefixed and sent to the configured :device (defaulting to :stdio).

# A daemon that accumulates all output lines into a list
args = [
  command: "echo",
  args: ["hello world"],
  handle_data: {[], fn lines, acc -> acc ++ lines end}
]

{:ok, _pid} = Owl.Daemon.start(args)

Owl.Spinner.run/2 (Automatic)

• Best for: Simple, single-task operations where you don't need to change the status message mid-task.
• Lifecycle: Starts $\rightarrow$ Executes function $\rightarrow$ Stops based on return value.
• Limitation: You cannot call update_label/1 to change the text while the function is running.

Owl.Spinner.start/1 (Manual)

• Best for: Complex workflows where you want to update the user on progress (e.g., "Step 1/3", "Step 2/3").
• Lifecycle: Requires explicit calls to start/1 and stop/1.
• Advantage: Allows calling update_label/1 at any point during the task execution.

The Owl.LiveScreen module is a server that manages live-updating, multi-line blocks in a terminal. It implements the Erlang I/O protocol, allowing it to be used as an I/O device for Logger or standard IO functions. When used this way, standard output is printed above the dynamic blocks, preventing logs from overwriting your UI.

Core Workflow

1. Add a block: Define a block_id and a render function that transforms a state into a view (using Owl.Data.t()).
2. Update state: Use update/3 to change the data associated with a block.
3. Wait for render: Use await_render/1 to ensure the UI has caught up with your latest state changes before proceeding.

Owl.LiveScreen.add_block(:status, state: "starting...")
Owl.LiveScreen.update(:status, "done!")
Owl.LiveScreen.await_render()

To use Owl.LiveScreen as a destination for Logger (so logs appear above your UI blocks), add it as a handler.

Note for OTP 28+: When using the handler ID :default, you must explicitly set filter_default: :log and filters: []. Otherwise, OTP 28's default behavior may silently drop Elixir log events.

:ok = :logger.remove_handler(:default)

:ok = :logger.add_handler(:default, :logger_std_h, %{
  config: %{type: {:device, Owl.LiveScreen}},
  formatter: Logger.Formatter.new(),
  # Required for OTP 28+ compatibility
  filter_default: :log,
  filters: []
})

You can combine Owl.TrueColor sequences with Owl.Data.tag/2 to apply specific foreground and background colors to strings before outputting them with Owl.IO.puts/1.

"Hello"
  |> Owl.Data.tag([Owl.TrueColor.color(1, 244, 74), Owl.TrueColor.color_background(133, 48, 100)])
  |> Owl.IO.puts()

You can run multiple progress bars concurrently by assigning each a unique :id. This is common when using Task.async to track parallel operations.

1..10
|> Enum.map(fn index ->
  Task.async(fn ->
    range = 1..Enum.random(100..500)
    label = "Demo Progress ##{index}"

    Owl.ProgressBar.start(
      id: {:demo, index},
      label: label,
      total: range.last,
      timer: true,
      bar_width_ratio: 0.3,
      filled_symbol: "#",
      partial_symbols: []
    )

    Enum.each(range, fn _ ->
      Process.sleep(Enum.random(10..50))
      Owl.ProgressBar.inc(id: {:demo, index})
    end)
  end)
end)
|> Task.await_many(:infinity)

Owl.LiveScreen.await_render()

If you receive data that already contains ANSI escape sequences (e.g., from a subprocess like bat), use Owl.Data.from_chardata/1 to parse those sequences into Owl.Tag structures. This allows you to use Owl's layout tools (like Owl.Box) on pre-colored text.

# Example: Parsing output from a system command
{output, 0} = Owl.System.cmd("bat", ["README.md", "--color=always"])

tagged_data = Owl.Data.from_chardata(output)