2lab-ai/using-terminal-charts

Terminal Charts with chartli

Render numeric data as terminal charts using chartli — supports ASCII line, sparklines, horizontal bars, columns, heatmap, unicode bars, braille, and SVG output.

Quick Reference

npx chartli <file> -t <type> [-w <width>] [-h <height>] [-m <mode>]

| Type | Best For | Key Options | |------|----------|-------------| | ascii | Line charts with axes | -w width, -h height | | spark | Compact inline trends | (none) | | bars | Horizontal bar comparison | -w width | | columns | Vertical bar comparison | -h height | | heatmap | Multi-series density view | (none) | | unicode | Detailed vertical bars | (none) | | braille | High-density scatter/line | -w width, -h height | | svg | File export, embedding | -m circles\|lines, -w, -h |

Input Data Format

Whitespace-separated numeric rows. Optional header row (non-numeric first row is treated as labels).

Single Series

day value
1 10
2 20
3 15
4 30
5 25

Multi Series

day sales costs profit
1 10 8 2
2 14 9 5
3 12 11 3
4 18 10 8

Multi-series data renders separate series for spark, bars, heatmap, and unicode types. Single-series types (ascii, braille) use the first numeric column.

Usage Patterns

From File

npx chartli data.txt -t ascii -w 40 -h 10
npx chartli data.txt -t spark
npx chartli data.txt -t bars -w 28

From Stdin (pipe)

printf 'x y\n1 10\n2 20\n3 15\n4 30\n' | npx chartli -t ascii -w 24 -h 8

From Command Output

Generate a temp data file from any command output, then chart it:

# Line counts per file
wc -l src/*.ts | grep -v total | awk '{print NR, $1}' > /tmp/chart-data.txt
npx chartli /tmp/chart-data.txt -t bars -w 30

# Git commits per day (last 30 days)
git log --since="30 days ago" --format='%ad' --date=short | sort | uniq -c | awk '{print NR, $1}' > /tmp/chart-data.txt
npx chartli /tmp/chart-data.txt -t ascii -w 40 -h 10

# Process memory usage over time
ps aux | sort -k4 -rn | head -10 | awk '{print NR, $4}' > /tmp/chart-data.txt
npx chartli /tmp/chart-data.txt -t bars -w 30

SVG Export

npx chartli data.txt -t svg -m lines -w 320 -h 120 | sed -n '/^<?xml/,$p' > chart.svg

The sed filter strips the chartli banner. Use -m circles (default) or -m lines for SVG style.

Type Selection Guide

• Quick trend overview → spark (most compact, one line per series)
• Values with axes → ascii (classic line chart with scale)
• Compare magnitudes → bars (horizontal) or columns (vertical)
• Dense multi-series → heatmap (grid with shading) or unicode (grouped vertical bars)
• High resolution → braille (2x4 dot matrix per character cell)
• Export/embed → svg (vector output for docs/web)

Common Dimensions

| Context | Suggested | |---------|-----------| | Inline / compact | -w 24 -h 6 | | Standard terminal | -w 40 -h 10 | | Wide terminal | -w 60 -h 15 | | SVG export | -w 320 -h 120 |

Notes

• npx chartli auto-installs on first run (no global install needed)
• Banner header prints to stdout — use 2>/dev/null to suppress stderr, or sed -n '/^<?xml/,$p' for SVG
• All numeric values are normalized to 0–1 range internally
• Empty or non-numeric rows are skipped