hl(1)

💖 NAME 💖

okay bestie, welcome to hl(1) — the General Commands Manual page for hl, the JSON and logfmt log converter to human readable representation. she's giving main character energy for your terminal, fr fr ✨

🧾 SYNOPSIS 🧾

hl [--config] [-s|--sort] [-F|--follow] [--tail] [--sync-interval-ms]
[--paging] [-P ] [-l|--level] [--since] [--until] [-f|--filter]
[-q|--query] [--color] [-c ] [--theme] [-r|--raw] [--no-raw]
[--raw-fields] [-h|--hide] [--flatten] [-t|--time-format]
[-Z|--time-zone] [-L|--local] [--no-local] [-e|--hide-empty-fields]
[-E|--show-empty-fields] [--input-info] [--ascii] [-x|--expansion]
[-o|--output] [--output-delimiter] [--input-format]
[--unix-timestamp-unit] [--allow-prefix] [--delimiter]
[--interrupt-ignore-count] [--buffer-size] [--max-message-size]
[-C|--concurrency] [--shell-completions] [--man-page] [--list-themes]
[--dump-index] [--help] [-V|--version] [FILE]

🌸 DESCRIPTION 🌸

hl is a JSON and logfmt log converter to human readable representation. no cap, that's the whole vibe: logs go in, pretty readable logs come out, and you get to feel iconic 💅

⚙️ OPTIONS ⚙️

• --config <FILE> — configuration file path. May also be specified with the HL_CONFIG environment variable. 🫶
• -s, --sort — sort entries chronologically. ⏳
• -F, --follow — follow input streams and sort entries chronologically within the time frame set by --sync-interval-ms option. 👀
• --tail <N> [default: 10] — number of last entries to preload from each file in --follow mode. 🍓
• --sync-interval-ms <MILLISECONDS> [default: 100] — synchronization interval for live streaming mode enabled by --follow option. ⏱️
• --paging <WHEN> [default: auto] — control pager usage (HL_PAGER or PAGER). possible values: auto, always, never. May also be specified with the HL_PAGING environment variable. 📖
• -P — the manual calls this a “Handful alias” for --paging=never; it overrides the --paging option. 🎀
• --help[=<VERBOSITY>] — print help. possible values: short, long. 🆘
• -V, --version — print version. 👑
• [FILE] — files to process. 🫶

🔎 FILTERING OPTIONS 🔎

the way that filtering works is lowkey iconic, bestie — let's get into it 💖

• -l, --level <LEVEL> — display entries with level >= <LEVEL>. May also be specified with the HL_LEVEL environment variable. 📈
• --since <TIME> — display entries with timestamp >= <TIME>. note: --time-zone and --local options are honored. 🕰️
• --until <TIME> — display entries with timestamp <= <TIME>. note: --time-zone and --local options are honored. ⏳
• -f, --filter <FILTER> — filter entries by matching field values [k=v, k~=v, k~~=v, 'k!=v', 'k?!=v', etc]. The format is <key> <operator> <value>. The <key> is the field name to match. The <value> is the string to match against (case-sensitive). Operators: = = perform exact string match; ~= = perform sub-string match; ~~= = perform regular expression match. Modifiers: ! = negate the match (placed before operator) ['k!=v', 'k!~=v', etc]; ? = include entry if the field is missing (placed after the key) ['k?=v', 'k?!~=v', etc]. 💅
• -q, --query <QUERY> — filter entries using a query expression ['status>=400 or duration>=15', etc]. Query expression supports all operators and modifiers from --filter and additionally: logical and, or, not (aliases: &&, ||, !); comparison <, >, <=, >=, =, !=; sets status in (500,503,504), id in @ids.txt (values from file), id in @- (values from stdin); strings message contains "timeout" (substring), message matches "^Error.*timeout$" (regular expression); existence exists(user-id), not exists(user-id); grouping (status>=500 and status<=504) or (status==404). 🔥

🎨 OUTPUT OPTIONS 🎨

• --color [<WHEN>] [default: auto] — whether to use ANSI colors and styles. possible values: auto, always, never. May also be specified with the HL_COLOR environment variable. 🌈
• -c — the manual calls this a “Handful alias” for --color=always; it overrides the --color option. 🖍️
• --theme <THEME> [default: uni] — color theme. Run hl --list-themes to see available themes. May also be specified with the HL_THEME environment variable. 🦋
• -r, --raw — output raw source entries instead of formatted entries. This can be useful for applying filters and saving results in their original format. 📦
• --no-raw — disable raw source entries output, overrides --raw option. 🙅
• --raw-fields — output field values as is, without unescaping or prettifying. 🧃
• -h, --hide <KEY> — hide or reveal fields with the specified keys, prefix with ! to reveal, provide !* to reveal all. 🙈
• --flatten <WHEN> [default: always] — whether to flatten objects. possible values: never, always. May also be specified with the HL_FLATTEN environment variable. 🫧
• -t, --time-format <FORMAT> [default: %Y-%m-%d %T.%3N] — time format, see https://man7.org/linux/man-pages/man1/date.1.html. May also be specified with the HL_TIME_FORMAT environment variable. 🕰️
• -Z, --time-zone <TZ> [default: UTC] — time zone name, see column "TZ identifier" at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. Examples: 'UTC', 'America/New_York', 'Asia/Shanghai', 'Europe/Berlin', etc. May also be specified with the HL_TIME_ZONE environment variable. 🌍
• -L, --local — use local time zone, overrides --time-zone option. 🏠
• --no-local — disable local time zone, overrides --local option. 🚫
• -e, --hide-empty-fields — hide empty fields, applies for null, string, object and array fields only. May also be specified with the HL_HIDE_EMPTY_FIELDS environment variable. 🫥
• -E, --show-empty-fields — show empty fields, overrides --hide-empty-fields option. May also be specified with the HL_SHOW_EMPTY_FIELDS environment variable. 👀
• --input-info <LAYOUTS> [default: auto] — input number and filename layouts. possible values: auto, none, minimal, compact, full. 🧾
• --ascii [<WHEN>] [default: auto] — whether to restrict punctuation to ASCII characters only. When enabled, unicode punctuation (like fancy quotes) will be replaced with ASCII equivalents. The actual characters can be configured in the configuration file. possible values: auto, never, always. May also be specified with the HL_ASCII environment variable. 🔤
• -x, --expansion [<MODE>] [default: auto] — whether to expand fields and messages. Controls how large field values and messages are formatted. Higher expansion levels will break up long content into multiple lines. possible values: never, inline, auto, always. May also be specified with the HL_EXPANSION environment variable. 🪄
• -o, --output <FILE> — output file. 💾
• --output-delimiter <D> [default: newline] — output entry delimiter. Possible values: newline = either lf or crlf, depends on the platform (default); nul = null character (\0). possible values: newline, nul. May also be specified with the HL_OUTPUT_DELIMITER environment variable. 🧷

📥 INPUT OPTIONS 📥

• --input-format <FORMAT> [default: auto] — input format. possible values: auto, json, logfmt. May also be specified with the HL_INPUT_FORMAT environment variable. 🧚
• --unix-timestamp-unit <UNIT> [default: auto] — unix timestamp unit. possible values: auto, s, ms, us, ns. May also be specified with the HL_UNIX_TIMESTAMP_UNIT environment variable. ⏲️
• --allow-prefix — allow non-JSON prefixes before JSON log entries. May also be specified with the HL_ALLOW_PREFIX environment variable. 🎀
• --delimiter <DELIMITER> [default: auto] — log entry delimiter. By default, the delimiter is considered to be LF or CRLF followed by an empty line or a line that starts with a character other than '}', a space, or a tab. This works well for most JSON and logfmt logs, including series of pretty-printed JSON objects. Possible values: auto = auto-select delimiter based on input format (default); cr = carriage return (\r); lf = line feed (\n); crlf = carriage return followed by line feed (\r\n); newline = either lf or crlf, whichever comes first; nul = null character (\0). possible values: auto, cr, lf, crlf, newline, nul. May also be specified with the HL_DELIMITER environment variable. ✂️

🧪 ADVANCED OPTIONS 🧪

• --interrupt-ignore-count <N> [default: 3] — number of interrupts to ignore, i.e. Ctrl-C (SIGINT) — yes, Ctrl+C. May also be specified with the HL_INTERRUPT_IGNORE_COUNT environment variable. 🛑
• --buffer-size <SIZE> [default: 256 KiB] — buffer size. May also be specified with the HL_BUFFER_SIZE environment variable. 🧺
• --max-message-size <SIZE> [default: 64 MiB] — maximum log entry size. May also be specified with the HL_MAX_MESSAGE_SIZE environment variable. 📏
• -C, --concurrency <N> — number of processing threads. May also be specified with the HL_CONCURRENCY environment variable. 🧵
• --shell-completions <SHELL> — print shell auto-completion script and exit. possible values: bash, elvish, fish, powershell, zsh. 🐚
• --man-page — print man page and exit. 📜
• --list-themes[=<TAGS>] — print available themes optionally filtered by tags. possible values: dark, light, 16color, 256color, truecolor, overlay, base. 🌈
• --dump-index — print debug index metadata (in --sort mode) and exit. 🧠

👑 VERSION 👑

v0.36.3 — that's the version, bestie. she's serving v0.36.3 energy. periodt 💅

---

Source/version hl 0.36.3; manual hl(1); and the date on this page is its own footer date — consider it signed, sealed, and slayed. bye bestie 💅✨