glint

README

glint

glint is a bounded-memory Windows command-line tool for displaying and following one local or UNC-hosted text log file. It reads only the requested startup suffix, keeps a single source handle open while following, and detects common truncation and replacement patterns.

Documentation:

• User guide
• Developer guide
• Technical specification
• Changelog

Install

Download the ZIP for windows_amd64 or windows_arm64 from a release and place glint.exe on PATH. The executable is self-contained and does not require a Go installation.

To build from source:

go build -trimpath -o glint.exe .

Usage

glint [flags] <path>

# Print the last 10 lines, then follow
glint C:\logs\application.log

# Relative paths resolve from the current working directory
glint .\logs\application.log

# Follow a UNC source with the current Windows security context
glint "\\appserver01\logs$\payments\application.log"

# Select startup content
glint --lines 200 C:\logs\application.log
glint --bytes 64KiB C:\logs\application.log
glint --all C:\logs\application.log

# Print and exit
glint --no-follow --lines 100 C:\logs\application.log

# Wait for a file created by a future process, but stop successfully after 30m
glint --wait-for-file --timeout 30m C:\logs\scheduled.log

# Follow an existing file for 10 minutes, then stop successfully
glint --timeout 10m C:\logs\application.log

# Stop after 30 seconds without new source data
glint --exit-after-idle 30s C:\logs\batch-job.log

# Include errors and warnings, except routine health checks
glint --match "(?i)error|warn" --not-match "healthcheck" .\logs\application.log

# Stop after writing a decoded line that matches a Go regular expression
glint --until-match "^Server ready$" --timeout 2m .\logs\application.log

# Keep the 200 lines before a match quiet, then print that context and the match
glint --flight-recorder 200 --until-match "(?i)panic|fatal" .\logs\application.log

# Hear rate-limited activity clicks and a triple click for serious lines
glint --geiger-counter --alarm-match "(?i)panic|fatal" .\logs\application.log

# Hear load as pitch and health severity as octave
glint --sound-activity --warn-match "(?i)warn" --error-match "(?i)error" `
  --critical-match "(?i)panic|fatal" .\logs\application.log

# Persist tool diagnostics locally (source content is never written here)
glint --diagnostic-log "$env:LOCALAPPDATA\glint\glint.log" C:\logs\application.log

Run glint --help for every option. --all, --bytes, and an explicitly provided --lines are mutually exclusive.

Activity sound uses a fixed low-amplitude waveform, a 160–2,500 Hz pitch band, soft edge fades, and at most a 50% duty cycle. Actual sound pressure still depends on Windows and the playback hardware; begin with a low device volume.

File lifecycle behavior

The default rotation policy is follow-name: glint drains the open file, then follows a replacement created at the configured path. Alternative policies are follow-handle and stop.

When the current file is truncated below the read offset, the default is to restart at byte zero. --on-truncate=end waits at the new end and --on-truncate=stop exits.

Temporary source failures use exponential backoff when retry is enabled. Retry defaults to enabled for UNC paths and disabled for local paths. Access denied is terminal; establish SMB credentials outside glint.

Configuration

Configuration precedence is flags, GLINT_ environment variables, configuration file, then defaults. Files are searched in this order:

1. %APPDATA%\glint\config.yaml
2. %LOCALAPPDATA%\glint\config.yaml
3. .glint.yaml in the current directory

Use --config for an explicit file or --no-config to disable file loading.

wait_for_file: false
timeout: 0s
exit_after_idle: 0s
match: ""
not_match: ""
until_match: ""
flight_recorder: 0
geiger_counter: false
alarm_match: ""
sound_activity: false
sound_scope: raw
warn_match: ""
error_match: ""
critical_match: ""
poll_interval: 1s
retry: true
retry_initial: 1s
retry_max: 30s
retry_timeout: 0s
rotation: follow-name
on_truncate: restart
encoding: utf-8
max_line_bytes: 1MiB
long_line: split
read_buffer: 64KiB
diagnostic_level: warn
diagnostic_log_max_size: 10MiB
diagnostic_log_backups: 3

Supported encodings are utf-8, utf-8-bom, utf-16le, windows-1252, and raw. Decoded output is UTF-8. raw preserves bytes.

User-controlled allocations have hard limits: --read-buffer is capped at 4 MiB, --max-line-bytes at 16 MiB, flight-recorder payload at 64 MiB and 100,000 entries, regular expressions at 64 KiB each, and configuration files at 1 MiB. Recorder context evicts its oldest lines when either recorder limit is reached.

Output and exit codes

Source content is written only to stdout. Diagnostics are written to stderr and, when configured, as rotating JSON Lines in the local diagnostic log.

Code	Meaning
0	Success, clean interruption, configured timeout, idle exit, or match
2	Invalid argument or configuration
3	Source not found
4	Access denied
5	Unsupported path, encoding, or file type
6	Source I/O failure or retry timeout
7	Output failure
8	Required diagnostic initialization failure
10	Internal failure

Development

.\scripts\ci.ps1

GitHub Actions jobs execute on a Windows self-hosted runner, so builds and checks run on the local machine rather than GitHub-hosted infrastructure. Release archives and checksums are produced by the pinned GoReleaser workflow. UNC/SMB behavior should additionally be exercised against a real Windows share in the target environment.