Terminal Logger

TerminalLogger is the Logger component’s console backend. It writes colorized, level-aware lines to stdout/stderr, with optional timestamps, symbols, structured data, and formatted stack traces. That makes it the natural choice for local development and CLI output. It implements the framework’s ILogger interface, so call sites stay provider-agnostic and you can swap to a remote or database backend without touching the code that emits logs.

What it prints

There’s nothing to configure: no tokens, hosts, or connection strings, so it works the moment you resolve it. Each level (ERROR, WARN, INFO, DEBUG, LOG, SUCCESS) prints in its own color with its own symbol. Pass a data object and the scalar fields render as colorized key: value pairs. Hand error() an IException and it renders the name, status, and a formatted stack trace. Any call can toggle showArrow, showTimestamp, showLevel, and useSymbol. The class registers with @decorator.logger() and resolves from the container.

Installation

TerminalLogger ships with @talosjs/logger.

bun add @talosjs/logger

It uses Bun.color for ANSI colorization, so it runs under the Bun runtime with no extra dependencies.

Environment variables

TerminalLogger needs no configuration. There are no environment variables to set.

How it works

Each level method formats a single line and writes it to the console. The line is assembled from an arrow, a timestamp, the level (as [LEVEL] or a symbol), and the colorized message. Any scalar fields in data are appended as colorized key: value pairs, and when an IException is passed to error(), its structured stack trace is rendered frame by frame. ERROR-level lines (and FATAL) are written to stderr; everything else goes to stdout.

Method	Purpose
`init()`	No-op; returns immediately.
`error(message, data?, options?)`	Log an error. `message` may be a `string` or `IException`.
`warn(message, data?, options?)`	Log a warning.
`info(message, data?, options?)`	Log informational output.
`debug(message, data?, options?)`	Log debug detail.
`log(message, data?, options?)`	Log a general message.
`success(message, data?, options?)`	Log a success message.

The per-call display options (LoggerOptionsType):

Option	Type	Purpose
`showArrow`	`boolean`	Show the leading `->` arrow. Defaults to `true`.
`showTimestamp`	`boolean`	Show the `YYYY-MM-DD HH:mm:ss` timestamp. Defaults to `true`.
`showLevel`	`boolean`	Show the level label. Defaults to `true`.
`useSymbol`	`boolean`	Render the level as a symbol instead of `[LEVEL]`. Defaults to `false`.

Usage

import { container } from "@talosjs/container";
import { TerminalLogger } from "@talosjs/logger";

const logger = container.get(TerminalLogger);

logger.info("User signed in", { userId: "123", email: "john@example.com" });
logger.success("Payment captured", { orderId: "ord_456", amount: 4999 });
logger.warn("Rate limit approaching", { remaining: 5 });

// Control terminal rendering per call
logger.debug("Cache miss", { key: "user:123" }, { useSymbol: true, showTimestamp: false });

error() accepts a plain message or an IException. Given an exception, it renders the name, status, and a formatted stack trace:

import { container } from "@talosjs/container";
import { TerminalLogger } from "@talosjs/logger";
import type { IException } from "@talosjs/exception";

const logger = container.get(TerminalLogger);

try {
  await processPayment(order);
} catch (error) {
  logger.error(error as IException, { orderId: order.id });
}

Inject it into a service to log as part of your domain logic:

import { inject } from "@talosjs/container";
import { TerminalLogger } from "@talosjs/logger";

export class PaymentService {
  constructor(@inject(TerminalLogger) private readonly logger: TerminalLogger) {}

  public capture(order: Order) {
    this.logger.success("Payment captured", { orderId: order.id, amount: order.total });
  }
}

Use in the app

In an @talosjs/app application, register TerminalLogger by adding it to the loggers array of your App config. The loggers slot of AppConfigType is typed as LoggerClassType[], so you pass the class itself and the framework registers it with the container at startup.

bun add @talosjs/app @talosjs/logger

import { App } from "@talosjs/app";
import { TerminalLogger } from "@talosjs/logger";

const app = new App({
  routing: { prefix: "/api" },
  loggers: [TerminalLogger],
});

await app.run();

loggers accepts an array, so you can register more than one backend at once, for example terminal output alongside a persistent backend:

import { App } from "@talosjs/app";
import { DatabaseLogger, TerminalLogger } from "@talosjs/logger";

const app = new App({
  routing: { prefix: "/api" },
  loggers: [TerminalLogger, DatabaseLogger],
});

Once registered, inject it into a service or controller and log as part of your domain logic:

import { inject } from "@talosjs/container";
import { TerminalLogger } from "@talosjs/logger";

export class CheckoutService {
  constructor(@inject(TerminalLogger) private readonly logger: TerminalLogger) {}

  public async completeOrder(userId: string, order: Order) {
    // ... persist the order ...
    this.logger.success("Order completed", { userId, orderId: order.id });
  }
}

Because TerminalLogger needs no configuration, it’s ideal as the development default. To move to a remote or persistent backend in production (see Better Stack Logger, or write your own against ILogger), change which class you register.

Getting readable output

This is your zero-config development default; in production, ship to a remote or database backend instead. Keep the message string stable and push variable detail into the data object rather than interpolating it into the text. When you catch an exception, pass the IException itself to error() so the name, status, and stack trace are rendered. Per call, use options to drop the timestamp or switch to symbols for compact CLI output. One thing to remember: only scalar fields (string, number, boolean, bigint) in data are rendered, and nested objects are skipped. See the Logger component for the provider interface and how logs flow through the framework.

Getting Started

AI

Framework

Command Line

Terminal Logger

What it prints

Installation

Environment variables

How it works

Usage

Use in the app

Getting readable output

​What it prints

​Installation

​Environment variables

​How it works

​Usage

​Use in the app

​Getting readable output

What it prints

Installation

Environment variables

How it works

Usage

Use in the app

Getting readable output