---
obj: application
repo: https://github.com/pamburus/hl
----

# hl
High-performance log viewer and processor that transforms logs in JSON and logfmt formats into a human-readable output. Built with efficiency in mind, it enables quick parsing and analysis of large log files with minimal overhead.

## Usage
Usage: `hl [OPTIONS] [FILE]...`

| Option                              | Environment  | Description                                                                                          |
| ----------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
| `--config <FILE>`                   | `$HL_CONFIG` | Configuration file path                                                                              |
| `-s`, `--sort`                      |              | Sort messages chronologically                                                                        |
| `-F`, `--follow`                    |              | Follow input streams and sort messages chronologically during time frame set by `--sync-interval-ms` |
| `--tail <N>`                        |              | Number of last messages to preload in `--follow` mode (default: 10)                                  |
| `--sync-interval-ms <MILLISECONDS>` |              | Synchronization interval for live streaming (default: 100)                                           |
| `--paging <WHEN>`                   | `$HL_PAGING` | Control pager usage (default: auto) [auto, always, never]                                            |
| `-P`                                |              | Alias for `--paging=never`, overrides `--paging`                                                     |
| `--help`                            |              | Print help                                                                                           |
| `-V`, `--version`                   |              | Print version                                                                                        |

### Filtering Options

| Option                    | Environment | Description                                         |
| ------------------------- | ----------- | --------------------------------------------------- |
| `-l`, `--level <LEVEL>`   | `$HL_LEVEL` | Filter messages by level                            |
| `--since <TIME>`          |             | Filter messages by timestamp >= TIME                |
| `--until <TIME>`          |             | Filter messages by timestamp <= TIME                |
| `-f`, `--filter <FILTER>` |             | Filter by field values, e.g. `k=v`, `k~=v`, `k~~=v` |
| `-q`, `--query <QUERY>`   |             | Filter using query expressions                      |

### Output Options

| Option                         | Environment             | Description                                                                |
| ------------------------------ | ----------------------- | -------------------------------------------------------------------------- |
| `--color [<WHEN>]`             | `$HL_COLOR`             | Control color output (default: auto) [auto, always, never]                 |
| `-c`                           |                         | Alias for `--color=always`, overrides `--color`                            |
| `--theme <THEME>`              | `$HL_THEME`             | Set color theme (default: uni)                                             |
| `-r`, `--raw`                  |                         | Output raw source messages                                                 |
| `--no-raw`                     |                         | Disable raw output, overrides `--raw`                                      |
| `--raw-fields`                 |                         | Output raw field values without formatting                                 |
| `-h`, `--hide <KEY>`           |                         | Hide/reveal fields by key (use `!*` to reveal all)                         |
| `--flatten <WHEN>`             | `$HL_FLATTEN`           | Whether to flatten objects (default: always)                               |
| `-t`, `--time-format <FORMAT>` | `$HL_TIME_FORMAT`       | Time format (default: `%b %d %T.%3N`)                                      |
| `-Z`, `--time-zone <TZ>`       | `$HL_TIME_ZONE`         | Set time zone (default: UTC)                                               |
| `-L`, `--local`                |                         | Use local time zone                                                        |
| `--no-local`                   |                         | Disable local time zone                                                    |
| `-e`, `--hide-empty-fields`    | `$HL_HIDE_EMPTY_FIELDS` | Hide empty fields                                                          |
| `-E`, `--show-empty-fields`    | `$HL_SHOW_EMPTY_FIELDS` | Show empty fields, overrides hide option                                   |
| `--input-info <LAYOUTS>`       |                         | Set input info layout (default: auto) [auto, none, minimal, compact, full] |
| `-o`, `--output <FILE>`        |                         | Write output to file                                                       |

### Input Options

| Option                         | Environment               | Description                                                    |
| ------------------------------ | ------------------------- | -------------------------------------------------------------- |
| `--input-format <FORMAT>`      | `$HL_INPUT_FORMAT`        | Set input format (default: auto) [auto, json, logfmt]          |
| `--unix-timestamp-unit <UNIT>` | `$HL_UNIX_TIMESTAMP_UNIT` | Unit for Unix timestamps (default: auto) [auto, s, ms, us, ns] |
| `--allow-prefix`               | `$HL_ALLOW_PREFIX`        | Allow non-JSON prefixes                                        |
| `--delimiter <DELIMITER>`      |                           | Message delimiter, e.g. [NUL, CR, LF, CRLF, custom string]     |

### Advanced Options

| Option                         | Environment                  | Description                                                              |
| ------------------------------ | ---------------------------- | ------------------------------------------------------------------------ |
| `--interrupt-ignore-count <N>` | `$HL_INTERRUPT_IGNORE_COUNT` | Number of Ctrl-C signals to ignore (default: 3)                          |
| `--buffer-size <SIZE>`         | `$HL_BUFFER_SIZE`            | Set buffer size (default: "256 KiB")                                     |
| `--max-message-size <SIZE>`    | `$HL_MAX_MESSAGE_SIZE`       | Max message size (default: "64 MiB")                                     |
| `-C`, `--concurrency <N>`      | `$HL_CONCURRENCY`            | Number of processing threads                                             |
| `--shell-completions <SHELL>`  |                              | Print shell completion script [bash, elvish, fish, powershell, zsh]      |
| `--man-page`                   |                              | Print man page                                                           |
| `--list-themes[=<TAGS>]`       |                              | Print available themes, optionally filtered [dark, light, 16color, etc.] |
| `--dump-index`                 |                              | Print debug index metadata in `--sort` mode                              |