Headson

<h1 align="center"> <img src="https://raw.githubusercontent.com/kantord/headson/main/docs/assets/logo.svg" alt="headson" width="221" /> </h1> <p align="center"> <a href="#features">Features</a> · <a href="#install">Install</a> · <a href="#usage">Usage</a> · <a href="#python-bindings">Python bindings</a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/kantord/headson/main/docs/assets/tapes/demo.gif" alt="Terminal demo" width="1560" height="900" /> <br/> </p>

head/tail for JSON, YAML — but structure‑aware. Get a compact preview that shows both the shape and representative values of your data, all within a strict byte budget. (Just like head/tail, hson can also work with unstructured text files.)

Available as:

• CLI: Install · Usage
• Python library: Install · Usage

Features

• Budgeted output: specify exactly how much you want to see (bytes/chars/lines; per-file and global caps)
• Output formats: auto | json | yaml | text with styles strict | default | detailed
• Structure-aware parsing: full JSON/YAML parsing (preserves tree shape under truncation)
• Source code support: heuristic, indentation-aware summaries that keep lines atomic
• Multi-file mode: preview many files at once (paths, --glob ..., or --recursive on directories) with shared or per-file budgets
• Repo-aware ordering: in git repos, frequent+recent files show up first (rarely touched files drift to the end; mtime fallback)
• grep-like search and tree-like view: --grep <regex> and --tree emulate the workflows while still summarizing file contents inline
• Fast: processes gigabyte‑scale files in seconds (mostly disk‑bound)
• Available as a CLI app and as a Python library

Extra features

Source code mode

For source code files, headson uses an indentation-aware heuristic to build an outline, then picks representative lines from across that structure (while keeping lines atomic so omissions never split a line). Syntax highlighting is available when colors are enabled.

Learn more: Source code support

Grep mode

Guarantee that matching keys/values stay in view under tight budgets (supports multi-file mode via --glob).

Tree mode

Preview many files at once in a directory tree layout (inline previews, round‑robin fairness; supports multi-file mode via --glob).

Sorting

In multi-file mode, inputs are ordered so frequently and recently touched files show up first, and rarely touched files drift to the end (using git history when available, with mtime fallback). Use a global byte budget (--global-bytes) to get an up‑to‑date repo snapshot within a strict overall limit (and --chars when you want a per-file character cap).

Install

Using Cargo:

cargo install headson

Note: the package is called headson, but the installed CLI command is hson. All examples below use hson ....

From source:

cargo build --release
target/release/hson --help

Usage

hson [FLAGS] [INPUT...]

• INPUT (optional, repeatable): file path(s). If omitted, reads from stdin. Multiple input files are supported.
• Prints the preview to stdout. On parse errors, exits non‑zero and prints an error to stderr.

Quick examples

Peek a JSON stream from stdin:

curl -sS 'https://pokeapi.co/api/v2/pokemon?limit=151' | hson -c 800

Preview many files with a single total budget:

hson -c 200 -C 1200 logs/*.json

Machine-readable preview (strict JSON):

hson -c 200 -f json -t strict data.json

YAML with detailed comments:

hson -c 400 -f yaml -t detailed config.yaml

Keep matches visible (grep-like) while still summarizing structure:

hson --grep 'error|warning' -c 200 -C 1200 logs/*.json

Tree-like view with inline previews:

hson --tree --glob 'src/**/*' -c 160 -C 1200

Source code outline (keeps lines intact; omits blocks under tight budgets):

hson -n 20 src/main.py

Detailed documentation

• Common flags
• Multi-file mode
• Grep mode
• Tree mode
• Budget modes
• Text mode
• Source code support

Common flags

• -c, --bytes <BYTES>: per‑file output budget (bytes). For multiple inputs, default total budget is <BYTES> * number_of_inputs.
• -u, --chars <CHARS>: per‑file output budget (Unicode code points). Behaves like --bytes but counts characters instead of bytes.
• -C, --global-bytes <BYTES>: total output budget across all inputs. With --bytes, the effective total is the smaller of the two.
• -f, --format <auto|json|yaml|text>: output format (default: auto).
  • Auto: stdin → JSON family; multi-file mode → per‑file based on extension (.json → JSON family, .yaml/.yml → YAML, unknown → Text).
• -t, --template <strict|default|detailed>: output style (default: default).
  • JSON family: strict → strict JSON; default → Pseudo; detailed → JS with inline comments.
  • YAML: always YAML; style only affects comments (strict none, default “# …”, detailed “# N more …”).
• -i, --input-format <json|yaml|text>: ingestion format (default: json). In multi-file mode with --format auto, ingestion is chosen by extensions.
• -m, --compact: no indentation, no spaces, no newlines
• --no-newline: single line output
• --no-header: suppress per-file section headers (useful when embedding output in scripts)
• --tree: render multi-file previews as a directory tree with inline previews (keeps code line numbers); uses per-file auto formatting.
• --no-space: no space after : in objects
• --indent <STR>: indentation unit (default: two spaces)
• --string-cap <N>: max graphemes to consider per string (default: 500)
• --grep <REGEX>: guarantee inclusion of values/keys/lines matching the regex (ripgrep‑style). Matches + ancestors are "free" against both global and per-file caps; budgets apply to everything else. If matches consume all headroom, only the must‑keep path is shown. Colors follow the normal on/auto/off rules; when grep is active, syntax colors are suppressed and only the match highlights are colored. JSON/YAML structural punctuation is not highlighted—only the matching key/value text.
• --igrep <REGEX>: case-insensitive variant of --grep.
• -r, --recursive: recursively expand directory inputs (like grep -r). Directory paths are required; stdin is not supported. Incompatible with --glob.
• --head: prefer the beginning of arrays when truncating (keep first N). Strings are unaffected. Display styles place omission markers accordingly; strict JSON remains unannotated. Mutually exclusive with --tail.
• --tail: prefer the end of arrays when truncating (keep last N). Strings are unaffected. Display styles place omission markers accordingly; strict JSON remains unannotated. Mutually exclusive with --head.

Notes:

• Multiple inputs:
  • With newlines enabled, file sections are rendered with human‑readable headers (pass --no-header to suppress them). In compact/single‑line modes, headers are omitted.
  • Order: in git repos, files are ordered so frequently and recently touched files show up first, with mtime fallback; pass --no-sort to keep the original input order without repo scanning.
  • Fairness: file contents are interleaved round‑robin during selection so tight budgets don’t starve later files.
• In --format auto, each file uses its own best format: JSON family for .json, YAML for .yaml/.yml.
  • Unknown extensions are treated as Text (raw lines) — safe for logs and .txt files.
  • --global-bytes may truncate or omit entire files to respect the total budget.
  • Directories are ignored unless --recursive is set; binary files are ignored with a warning. Glob/recursive expansion respects .gitignore plus .ignore/.rgignore. Stdin reads the stream as‑is.
  • Head vs Tail sampling: these options bias which part of arrays are kept before rendering; strict JSON stays unannotated.

Multi-file mode

• Budgets: per-file caps (--bytes/--chars/--lines) apply to each input; global caps (--global-*) constrain the combined output when set. Default byte/char budgets scale by input count when no globals are set; line caps stay per-file unless you pass --global-lines.
• One metric per level: pick at most one per-file budget flag (--bytes | --chars | --lines) and at most one global flag (--global-bytes | --global-lines). Mixing per-file and global kinds is allowed (e.g., per-file lines + global bytes); conflicting flags error.
• Inputs: pass file paths directly, use --glob <PATTERN> to expand additional files, or --recursive to expand directory inputs (incompatible with --glob). Glob patterns are positive-only; use ignore files (.gitignore, .ignore, .rgignore) for exclusions.
• Sorting: inputs are ordered so frequently and recently touched files appear first (git metadata when available, mtime fallback). Pass --no-sort to preserve the order you provided and skip repo scanning.
• Headers: multi-file output gets ==> headers when newlines are enabled; hide them with --no-header. Compact and single-line modes omit headers auto