or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-tool.mdcolorization.mdconfiguration.mdcustom-prettifiers.mdindex.mdmessage-formatting.mdprettifier-factory.mdstream-transport.md
tile.json

cli-tool.mddocs/

CLI Tool

The pino-pretty command-line tool provides a full-featured interface for prettifying Pino logs via standard input. It supports extensive configuration through command-line arguments and configuration files.

Capabilities

Basic Usage

Pipe Pino logs to pino-pretty for formatted output.

# Basic usage
node app.js | pino-pretty

# With options
node app.js | pino-pretty --colorize --translateTime

# From file
cat logs.ndjson | pino-pretty --colorize

Usage Examples:

# Colorized output
node app.js | pino-pretty -c

# With timestamp translation
node app.js | pino-pretty -c -t

# Filter to info level and above
node app.js | pino-pretty -c -L info

# Custom message format
node app.js | pino-pretty -o '{levelLabel} [{pid}] {msg}'

# Ignore specific fields
node app.js | pino-pretty -c -i time,hostname,pid

Display Options

Colorize (-c, --colorize)

Enable terminal color output.

# Enable colors
pino-pretty --colorize
pino-pretty -c

# Disable colorization of objects (but keep level colors)
pino-pretty -c --no-colorizeObjects

Examples:

# Full colorization
node app.js | pino-pretty -c

# Colors with custom scheme
node app.js | pino-pretty -c -X 'info:blue,error:red'

CRLF (-f, --crlf)

Use Windows-style line endings.

# CRLF line endings
pino-pretty --crlf
pino-pretty -f

Example:

node app.js | pino-pretty -f > output.log

Level First (-l, --levelFirst)

Display log level before timestamp.

# Level first
pino-pretty --levelFirst
pino-pretty -l

Examples:

# Default: [10:30:45] INFO: hello
node app.js | pino-pretty

# Level first: INFO [10:30:45]: hello
node app.js | pino-pretty -l

Hide Object (-H, --hideObject)

Hide objects from output (except errors).

# Hide objects
pino-pretty --hideObject
pino-pretty -H

Example:

# Only show structured fields, not object details
node app.js | pino-pretty -H

Single Line (-S, --singleLine)

Print each log on a single line.

# Single line output
pino-pretty --singleLine
pino-pretty -S

Example:

# Multi-line becomes single line
node app.js | pino-pretty -S

Key Mapping Options

Message Key (-m, --messageKey)

Specify the message property key.

# Custom message key
pino-pretty --messageKey message
pino-pretty -m message

Example:

# If logs use 'message' instead of 'msg'
node app.js | pino-pretty -m message

Level Key (--levelKey)

Specify the level property key (supports nested keys).

# Custom level key
pino-pretty --levelKey level
pino-pretty --levelKey severity

# Nested level key
pino-pretty --levelKey meta.level

# Escaped dots (literal dot in property name)
pino-pretty --levelKey 'tags\.level'

Examples:

# Standard level key
node app.js | pino-pretty --levelKey level

# Nested property
node app.js | pino-pretty --levelKey 'log.severity'

Level Label (-b, --levelLabel)

Specify the token name for level label in messageFormat.

# Custom level label
pino-pretty --levelLabel severity
pino-pretty -b severity

Example:

node app.js | pino-pretty -b severity -o '{severity}: {msg}'

Timestamp Key (-a, --timestampKey)

Specify the timestamp property key.

# Custom timestamp key
pino-pretty --timestampKey time
pino-pretty -a timestamp

Example:

# If logs use 'ts' instead of 'time'
node app.js | pino-pretty -a ts

Error Like Object Keys (-k, --errorLikeObjectKeys)

Specify keys that contain error objects.

# Custom error keys (comma-separated)
pino-pretty --errorLikeObjectKeys err,error
pino-pretty -k exception,failure

Example:

# Add custom error key
node app.js | pino-pretty -k err,error,exception

Filtering Options

Minimum Level (-L, --minimumLevel)

Filter logs by minimum level.

# By level name
pino-pretty --minimumLevel info
pino-pretty -L warn

# By level number
pino-pretty -L 30

Examples:

# Show info and above (hide trace, debug)
node app.js | pino-pretty -L info

# Show warnings and errors only
node app.js | pino-pretty -L warn

# Show errors and fatal only
node app.js | pino-pretty -L error

Ignore (-i, --ignore)

Ignore specific properties (comma-separated).

# Ignore properties
pino-pretty --ignore hostname
pino-pretty -i pid,hostname

# Ignore nested properties
pino-pretty -i 'pid,req.headers'

# Ignore properties with literal dots
pino-pretty -i 'log\.domain\.corp/foo'

Examples:

# Hide hostname and pid
node app.js | pino-pretty -i hostname,pid

# Hide request headers
node app.js | pino-pretty -i req.headers,req.cookies

# Default is to ignore hostname
node app.js | pino-pretty

Include (-I, --include)

Include only specific properties (whitelist mode).

# Include only specific properties
pino-pretty --include level,time,msg
pino-pretty -I level,msg,userId

Examples:

# Show only level, time, and message
node app.js | pino-pretty -I level,time,msg

# Show specific fields
node app.js | pino-pretty -I level,msg,requestId,userId

# Include overrides ignore
node app.js | pino-pretty -i hostname -I level,msg,hostname
# Result: hostname IS shown

Formatting Options

Translate Time (-t, --translateTime)

Translate timestamps to human-readable format.

# Default format (HH:MM:ss.l in local time)
pino-pretty --translateTime
pino-pretty -t

# Custom format
pino-pretty -t 'yyyy-mm-dd HH:MM:ss'

# UTC time
pino-pretty -t 'UTC:yyyy-mm-dd HH:MM:ss.l o'

# System timezone
pino-pretty -t 'SYS:HH:MM:ss'
pino-pretty -t 'SYS:standard'

Examples:

# Simple time
node app.js | pino-pretty -t

# Full datetime
node app.js | pino-pretty -t 'yyyy-mm-dd HH:MM:ss.l'

# UTC
node app.js | pino-pretty -t 'UTC:HH:MM:ss'

# ISO format
node app.js | pino-pretty -t 'isoDateTime'

Message Format (-o, --messageFormat)

Custom message format template.

# Template with tokens
pino-pretty --messageFormat '{levelLabel} - {pid} - {msg}'
pino-pretty -o '{levelLabel} [{pid}] {msg}'

# With conditionals
pino-pretty -o '{levelLabel}{if pid} [{pid}]{end} - {msg}'

# With nested properties
pino-pretty -o '{levelLabel} - url:{req.url} - {msg}'

Examples:

# Simple template
node app.js | pino-pretty -o '{levelLabel}: {msg}'

# With PID
node app.js | pino-pretty -o '{levelLabel} [{pid}] {msg}'

# HTTP format
node app.js | pino-pretty -o '{method} {url} -> {statusCode} - {msg}'

# With conditionals
node app.js | pino-pretty -o '{levelLabel}{if requestId} [{requestId}]{end} - {msg}'

Error Props (-e, --errorProps)

Specify error properties to display.

# Error properties (comma-separated)
pino-pretty --errorProps stack,code,message
pino-pretty -e name,message,stack

Example:

# Show specific error properties
node app.js | pino-pretty -e stack,code,message

Custom Levels and Colors

Custom Levels (-x, --customLevels)

Define custom log levels.

# CSV format
pino-pretty --customLevels 'verbose:5,info:10,warning:40'
pino-pretty -x 'err:99,info:1'

Examples:

# Custom levels
node app.js | pino-pretty -x 'verbose:5,debug:10,info:20,warn:30,error:40,fatal:50'

# Simple custom levels
node app.js | pino-pretty -x 'low:10,medium:30,high:50'

Custom Colors (-X, --customColors)

Define custom level colors.

# CSV format
pino-pretty --customColors 'info:blue,warn:yellow,error:red'
pino-pretty -X 'err:red,info:blue'

# With default color
pino-pretty -X 'info:blue,error:red,default:gray'

Examples:

# Custom color scheme
node app.js | pino-pretty -c -X 'info:blue,warn:magenta,error:bgRed'

# With fallback
node app.js | pino-pretty -c -X 'info:green,error:red,default:white'

# Available colors: black, red, green, yellow, blue, magenta, cyan, white, gray
# Background colors: bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite

Use Only Custom Props (-U, --useOnlyCustomProps)

Control fallback to default levels/colors.

# Only use custom properties (default)
pino-pretty -U true

# Use custom + defaults
pino-pretty -U false

Examples:

# Strict custom levels only
node app.js | pino-pretty -x 'severe:99' -X 'severe:red' -U true

# Custom with fallback
node app.js | pino-pretty -x 'severe:99' -X 'severe:red' -U false

Configuration Files

Config File Support

Load options from configuration files.

# Specify config file
pino-pretty --config /path/to/config.json

# Auto-detect config files (searched in order):
# - pino-pretty.config.cjs
# - pino-pretty.config.js
# - .pino-prettyrc
# - .pino-prettyrc.json

Config File Formats:

// pino-pretty.config.js
module.exports = {
  colorize: true,
  translateTime: 'SYS:standard',
  ignore: 'pid,hostname',
  messageFormat: '{levelLabel} - {msg}'
};
// pino-pretty.config.cjs
module.exports = {
  colorize: true,
  levelFirst: true,
  customColors: {
    info: 'blue',
    error: 'red'
  }
};
// .pino-prettyrc or .pino-prettyrc.json
{
  "colorize": true,
  "translateTime": "HH:MM:ss",
  "ignore": "hostname",
  "singleLine": false
}

Usage Examples:

# Use specific config
node app.js | pino-pretty --config ./my-config.json

# Auto-detect config (checks current directory)
node app.js | pino-pretty

# CLI args override config
node app.js | pino-pretty --config ./config.json -c -t

Help

Display Help

Show help information.

# Show help
pino-pretty --help
pino-pretty -h

Example:

pino-pretty -h

Complete Examples

Development Setup

Typical development environment configuration.

# Full development setup
node app.js | pino-pretty \
  --colorize \
  --translateTime 'HH:MM:ss' \
  --ignore 'hostname' \
  --levelFirst

Production Debugging

Configuration for debugging production logs.

# Debug production logs
cat production.log | pino-pretty \
  --colorize \
  --translateTime 'SYS:standard' \
  --messageFormat '{levelLabel} [{pid}] {if requestId}[{requestId}] {end}{msg}' \
  --minimumLevel info

HTTP Request Logs

Format HTTP request logs.

# HTTP logs
node server.js | pino-pretty \
  --colorize \
  --translateTime 'HH:MM:ss' \
  --messageFormat '{method} {url} -> {statusCode} ({responseTime}ms)' \
  --include 'level,time,method,url,statusCode,responseTime,msg'

Error-Only Logs

Show only error and fatal logs.

# Errors only
node app.js | pino-pretty \
  --colorize \
  --minimumLevel error \
  --errorProps 'message,stack,code' \
  --translateTime 'yyyy-mm-dd HH:MM:ss'

Custom Level Application

Application with custom log levels.

# Custom levels app
node app.js | pino-pretty \
  --colorize \
  --customLevels 'verbose:5,debug:10,info:20,warn:30,error:40,critical:50' \
  --customColors 'verbose:gray,debug:blue,info:green,warn:yellow,error:red,critical:bgRed' \
  --useOnlyCustomProps false \
  --translateTime 'HH:MM:ss.l'

Minimal Output

Minimal, clean output for CI/CD.

# Minimal for CI
node app.js | pino-pretty \
  --no-colorize \
  --singleLine \
  --hideObject \
  --ignore 'hostname,pid' \
  --messageFormat '{levelLabel}: {msg}'

CLI Best Practices

Combining Options

Effective option combinations.

# Common combinations:

# Development
-c -t -i hostname

# Production debugging
-c -t 'SYS:standard' -L info

# Clean output
--no-colorize -S -H

# HTTP logging
-c -t -o '{method} {url} -> {statusCode}'

# Error focus
-L error -e message,stack,code

Config File vs CLI Args

When to use config files vs command-line arguments.

# Use config files for:
# - Shared team settings
# - Complex customPrettifiers (functions)
# - Consistent formatting across environments

# Use CLI args for:
# - Quick debugging
# - One-off log viewing
# - Override specific config values
# - Scripts and automation

Examples:

# Team config in .pino-prettyrc
node app.js | pino-pretty

# Override one setting
node app.js | pino-pretty -L debug

# Quick debug without config
cat logs.ndjson | pino-pretty -c -t -L info

Performance Tips

Optimize CLI performance for large log volumes.

# For large log files:
# - Disable colorization (faster)
# - Use singleLine mode
# - Use hideObject
# - Filter early with minimumLevel

cat large.log | pino-pretty --no-colorize -S -H -L info

Shell Limitations

Handle shell-specific issues.

# Git Bash / mingw64 on Windows may have issues
# Use Node.js directly instead:
node app.js | node node_modules/.bin/pino-pretty -c

# Or use WSL/PowerShell