LogTimeline

CLI timestamp normaliser, converter, and incident-response timeline builder

v1.0.2

NixOS x86_64

Quick Start

Install

curl -fsSL https://cli.johlem.net/install.sh | bash -s -- logtimeline

Uninstall

curl -fsSL https://cli.johlem.net/uninstall.sh | bash -s -- logtimeline

NixOS / Nix

nix profile install "tarball+https://cli.johlem.net/releases/cli-johlem-net-latest.tar.gz#logtimeline"

Features

15 timestamp formats: Unix epoch (s/ms/us), ISO 8601 (with TZ + ms), RFC 5424 syslog, Common Log Format, BSD syslog (RFC 3164), Windows FILETIME, Chrome/WebKit, macOS absolute time, LDAP/AD generalised, MySQL DATETIME, HTTP cookie / RFC 2822
Generic JSON event auto-detect — `@timestamp` / `timestamp` / `time` / `ts` fields, plus journalctl `__REALTIME_TIMESTAMP`
detect subcommand: enumerate every format that matches an input
Convert between any two formats with explicit --to target
diff subcommand: human + numeric time difference between any two timestamps
now subcommand: current time in UTC or any IANA timezone
Timeline builder: merge, sort, dedupe events from multiple log files
Anomaly markers in `timeline`: `--gap-threshold` (mark N-second gaps), `--burst-threshold` (mark K+ events per second)
Timeline filters: --after, --before, --grep, --max
Five output formats for `timeline`: text, JSON, CSV, markdown table, mermaid diagram
Timezone listing and side-by-side comparison via chrono-tz
Zero runtime dependencies — single static binary

Requirements

Runtime

NixOS x86_64 (built against nix-store glibc; zero extra runtime deps)

Dependencies

Zero third-party dependencies — Python standard library only.

Usage

logtimeline <command> [OPTIONS]

Run logtimeline --help to see every subcommand and flag, or logtimeline help <command> for per-command help.

Examples

Convert

$ logtimeline convert 1712793600
Input:    1712793600
UTC:      2024-04-11T00:00:00+00:00

Conversions:
  ISO 8601 / RFC 3339:    2024-04-11T00:00:00Z
  Common Log Format:      11/Apr/2024:00:00:00 +0000
  LDAP / Active Director: 20240411000000Z
  Windows FILETIME:       133572672000000000
  Unix epoch (seconds):   1712793600

Detect format

$ logtimeline detect 133580064000000000
Input:  133580064000000000
Possible formats:
  [HIGH  ] filetime  -> 2024-04-19T13:20:00+00:00 (Windows FILETIME)

Build a timeline from multiple log files

$ logtimeline timeline --input auth.log --input access.log
Timeline (5 events):
  2026-04-11T09:58:12Z  [auth.log]     Failed login for root from 10.0.0.5
  2026-04-11T09:58:15Z  [auth.log]     Failed login for root from 10.0.0.5
  2026-04-11T09:59:01Z  [access.log]   POST /admin/login 403 - 10.0.0.5
  2026-04-11T09:59:05Z  [access.log]   POST /admin/login 200 - 10.0.0.5
  2026-04-11T09:59:06Z  [auth.log]     Accepted password for admin

Timezone comparison

$ logtimeline tz compare 2026-04-11T10:00:00Z --zones Europe/Luxembourg,Asia/Tokyo
UTC:                   2026-04-11T10:00:00+00:00
Europe/Luxembourg:     2026-04-11T12:00:00+02:00
Asia/Tokyo:            2026-04-11T19:00:00+09:00

Install Layout

# Standard layout for all cli.johlem.net tools
~/.local/lib/logtimeline/                       # Tool source files
~/.local/bin/logtimeline                        # Executable wrapper
~/.local/log/cli.johlem.net/logtimeline_*.log   # Install/uninstall logs

After install, run logtimeline --help (requires ~/.local/bin in your PATH).

Changelog

# logtimeline — Changelog

## v1.0.2 — 2026-06-22

- Standardise exit codes per SUITE_STANDARDS.md §1 — clap usage errors and missing-subcommand now exit 2 (was 3). Runtime dispatch failures now exit 3 (was 2).

Integrity

Verify your download against these SHA256 checksums:

File	SHA256

This tool is provided as-is with no warranty. Use at your own risk. Always review scripts before running them. Not responsible for any damage or data loss. Intended for authorized security testing, research, and educational purposes only.

Release artefacts & provenance

Every signed release ships with checksum + signature sidecars plus a CycloneDX SBOM. Enterprise procurement can pin third-party components without unpacking the binary.

manifest.json — pinned SHA-256 + .sig URL + SBOM URL per platform
johlem-release.pub — Ed25519 public key used by signify -V (fingerprint: 4532510f…6748, pinned in jcli verify)
CHANGELOG.md — semver-tagged release notes
Security contact: security@johlem.net