histoterm

A lightweight Rust CLI tool that reads numeric data from stdin and prints an ASCII histogram showing the data distribution — perfect for quick data exploration right from the terminal.

🧩 Installation

Option 1 — From local source

cargo install --path .

This installs histoterm into Cargo’s bin directory (usually ~/.cargo/bin).

Option 2 — Directly from GitHub

Install the latest version straight from the repository:

cargo install --git https://github.com/zhanxw/histoterm

Or specify a branch, tag, or commit:

cargo install --git https://github.com/zhanxw/histoterm --branch main

🛠️ Build from source

If you just want to build without installing:

cargo build --release

The compiled binary will be at:

target/release/histoterm

🖼️ Preview

Here’s what histoterm looks like in action:

$ seq 100 | awk 'BEGIN{srand()} {for(i=0;i<int(rand()*3);i++) print $1}'   | histoterm --bins 12 --width 60

ASCII Histogram  (bins=12, width=60)
count = 86, min = 3.000000, max = 100.000000, mean = 47.639535, std = 29.028419

[3.0000     ,    11.0833) |     14 ( 16.3%) | ############################################################
[11.0833    ,    19.1667) |      4 (  4.7%) | #################
[19.1667    ,    27.2500) |     10 ( 11.6%) | ##########################################
[27.2500    ,    35.3333) |      7 (  8.1%) | ##############################
[35.3333    ,    43.4167) |      6 (  7.0%) | #########################
[43.4167    ,    51.5000) |      5 (  5.8%) | #####################
[51.5000    ,    59.5833) |      6 (  7.0%) | #########################
[59.5833    ,    67.6667) |     10 ( 11.6%) | ##########################################
[67.6667    ,    75.7500) |      4 (  4.7%) | #################
[75.7500    ,    83.8333) |      9 ( 10.5%) | ######################################
[83.8333    ,    91.9167) |      4 (  4.7%) | #################
[91.9167    ,   100.0000) |      7 (  8.1%) | ##############################

⚙️ Command-line options

🧮 Usage examples and piping

You can pipe any stream of numbers into histoterm.
Here are some practical examples:

1️⃣ From a CSV column

Use awk, cut, or csvkit to extract numeric data:

cut -d, -f3 data.csv | tail -n +2 | histoterm --bins 20

For tab-separated files:

awk -F'\t' '{print $5}' data.tsv | histoterm

2️⃣ From logs or JSON data

Extract numeric values from logs:

grep "latency=" server.log | sed 's/.*latency=//' | histoterm

From JSON data:

jq '.response_time' data.json | histoterm --bins 15

3️⃣ Combine with other tools

Chain with statistical or simulation outputs:

python -c "import numpy as np; [print(x) for x in np.random.normal(0,1,1000)]"   | histoterm --bins 20 --width 70

📄 License

GPLv3 License © 2025

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.