chartscii-cli

chartscii data.csv -c auto

Beautiful ASCII charts straight from your shell.

Pipe any data — numbers, CSV, JSON, du, git log, anything — and get a beautiful chart. Multiple chart types, no config files, no setup.

What's new

• ✅ Smart content parsing — auto-detects JSON, CSV, plain numbers, label+value pairs (in either order), size suffixes (K/M/G/T from du -sh), and numbers buried in strings ($1,500, Price: 99.99)
• ✅ Auto width & height — -w auto / -h auto snaps to your terminal dimensions; on horizontal charts, -w 80 produces output that actually fits in 80 columns (gutters and structure included)
• ✅ Auto file detection — pass the path directly (chartscii data.csv), no --file flag needed
• ✅ CLI-friendly color shorthand — -c "red,green,blue" for per-series, -c "0:red,1:green" for status maps, -c "gradient(red,blue:vertical:reverse)" for gradients — all parsed from one flag
• ✅ Type-aware defaults — --sort defaults off and --height jumps to 10 for non-bar chart types, so -Y line / -Y candlestick / -Y status look right out of the box
• ✅ Six chart types from one binary — bar, line, step, scatter, candlestick, status — switch with -Y
• ✅ Pipe-first design — works with du, git log, ps, find, wc, awk output, or anything else that emits text on stdout

Table of contents

• Installation
• Quick start
• Chart types
  • Bar
  • Line
  • Step
  • Scatter
  • Candlestick
  • Status
• Input formats
• Styling
• Stacked bars
• Animation
• Recipes & shell helpers
• Options reference
• License

Installation

npm install -g chartscii-cli

Then chartscii is on your $PATH. Don't want to install globally? Use npx chartscii.

Quick start

# from positional numbers
chartscii 10 20 30 40 50

# from a file (auto-detected)
chartscii data.csv
chartscii data.json

# from stdin
echo "1 2 3 4 5" | chartscii
seq 1 20 | chartscii

# from shell pipelines (sizes, columns, anything numeric)
du -sh * | chartscii -c auto

That's it — point any data source at chartscii and you get a chart.

Chart types

Switch the renderer with -Y / --type. Every type shares the core options (-w, -h, -t, -k, -c, -n, …) and adds its own knobs.

| Type | Best for | Key flags | |---|---|---| | bar (default) | rankings, totals, categorical comparisons | -o, -E, -I/-J/-K (stacked) | | line | trends over time, multi-series | -c "a,b,c" (per-series), -g | | step | piecewise-constant state | -N sharp/smooth, -O | | scatter | sparse points, distributions | -H, -C | | candlestick | OHLC market data | -c "bull,bear", -b | | status | dashboards, health grids | -c "key:color,...", -g |

Bar (default)

chartscii examples/example.json -k pastel

Vertical orientation with a gradient fill:

seq 1 12 | chartscii -o vertical -c "gradient(cyan,purple)" -f "░" -G auto -w auto

Line

Smooth 45° polyline through your data. Single- or multi-series.

echo "20 35 28 50 65 45 70 60 85 75 90 80" | \
  chartscii -Y line -c "gradient(cyan,purple)" -t "Monthly Trend" -w 80

Multi-series — pipe a JSON InputData[][] (one inner array per data point, one entry per series) and split colors on commas. Add -g for a legend, -U to label the entries:

chartscii series.json -Y line \
  -c "red,green,blue" \
  -g -B top -M right -U Q1 Q2 Q3 \
  -w 100

Step

Right-angle transitions for state that's piecewise-constant between samples. -N smooth rounds the corners with ╭╮╰╯.

echo "10 25 25 40 30 30 55 50 70 65" | \
  chartscii -Y step -N smooth -O -c "gradient(orange,pink)" -t "Step Smooth" -w 80

Scatter

Markers only — no connecting line. -c auto cycles the palette per point; -H overrides the marker char.

echo "12 45 28 65 30 80 55 22 70 90 35 50 60 18" | \
  chartscii -Y scatter -c auto -H "◈" -t "Distribution" -w 80

Candlestick

OHLC bars with bullish/bearish coloring. Each input point's value is [open, high, low, close] — feed them as a JSON array. -c "bull,bear" sets the two colors; doji (open == close) candles render as ─.

chartscii btc-month.json -Y candlestick \
  -c "green,red" \
  -t "BTC/USD — 30d" -w 160 -h 22 -b 2 -d 2

Status

A grid of colored cells — perfect for dashboards, host health, build matrices. Each cell's value is a status key (number or string) looked up in the -c map.

chartscii fleet.json -Y status \
  -c "0:red,1:green,2:yellow,3:blue" \
  -g -B top -M right -U down ok warning maint \
  -t "Fleet Status" -w 100 -b 4

For row mode (one labelled row per host, cells along the x-axis), give each input point a value: number[] instead of a single key.

Input formats

chartscii auto-detects what it's looking at. No --format flag needed.

Plain numbers

chartscii 1 2 3 4 5
echo "10 20 30" | chartscii
seq 1 100 | chartscii

Label + value

Both orderings work — chartscii figures it out.

echo -e "Item1 10\nItem2 20\nItem3 30" | chartscii   # label first
echo -e "10 Item1\n20 Item2\n30 Item3" | chartscii   # number first

Size suffixes

K, M, G, T are converted automatically. Means du -sh Just Works™.

du -sh * | chartscii -c auto -k pastel

Mixed strings

Numbers are extracted from any text — $1,500, Price: 99.99, 12.99$.

cat sales.txt | chartscii -c auto

CSV

JavaScript,68
TypeScript,56
Python,43

Stacked values support multiple notations:

JavaScript,[68, 21, 23]
TypeScript,56|11|10
Python,"43 10 5"
Go,32,8,4

chartscii examples/example-stacked.csv -c auto -p -k sport

JSON

[10, 20, 30, 40, 50]

Or with labels and per-bar overrides:

[
  { "label": "Jan", "value": 100, "color": "blue" },
  { "label": "Feb", "value": 150 }
]

For multi-series line / step / scatter, use InputData[][] — one inner array per data point, one entry per series:

[
  [{"label":"Jan","value":10}, {"label":"Jan","value":20}, {"label":"Jan","value":5}],
  [{"label":"Feb","value":15}, {"label":"Feb","value":12}, {"label":"Feb","value":8}]
]

For candlestick, value is [open, high, low, close]:

[
  [42100, 42850, 41800, 42600],
  [42600, 43200, 42400, 43050]
]

Styling

Colors

-c / --color accepts a lot of shapes — chartscii infers from context:

| Form | Example | Used by | |---|---|---| | Named / hex / ANSI | -c green, -c "#ff8800", -c 196 | any | | auto | -c auto | any (cycles palette) | | Gradient string | -c "gradient(red,yellow,green)" | any | | Gradient with direction / reverse | -c "gradient(cyan,pink:vertical:reverse)" | any | | Comma list (per-series) | -c "red,green,blue" | line / step / scatter | | Comma pair (bull/bear) | -c "green,red" | candlestick | | Status map | -c "0:red,1:green,2:yellow" | status |

chartscii 1 2 3 4 5 6 7 8 9 10 -c "gradient(red,yellow,green)" -t "Gradient"

Combine with -G auto to gradient-fill the empty space too:

seq 1 12 | chartscii -o vertical -c "gradient(purple,cyan)" -f "░" -G auto -w auto

Themes

chartscii --list-themes

default · pastel · lush · standard · beach · nature · neon · spring · pinkish · crayons · sunset · rufus · summer · autumn · mint · vintage · sport · rainbow · pool · champagne

chartscii examples/example.csv -c auto -p --no-sort -k beach

Fills, structure, alignment

# opt-in fill character (▒ by default, custom if a value is given)
chartscii 10 20 30 -f "░" -G blue

# bar alignment (horizontal: top/center/bottom/justify)
chartscii 10 20 30 -E center -h 10

# vertical alignment (left/center/right/justify)
chartscii 10 20 30 -o vertical -E center -w 60

# strip the box characters
chartscii 1 2 3 -n -c red

# customize the box characters
chartscii 1 2 3 -x "─" -y "│" -a "┃" -q "└"

Value labels

# show the raw value next to each bar
chartscii 100 250 500 -v

# with a currency prefix and three decimals
chartscii 1.234 5.678 9.012 -v -P '€' -V 3

# percentage labels, naturally
chartscii data.csv -p

Custom label format

-L / --label-format and -F / --value-label-format accept a template string:

| Placeholder | Where | Description | |---|---|---| | {label} | -L | The row label (with percentage if -p is on) | | {value} | -F | The value — for stacked bars, all segment values joined with \| | | {value:N} | -F | The N-th segment value (0-indexed). Out-of-range → empty |

# wrap labels in brackets, suffix values with €
chartscii data.csv -L "[{label}]" -F "{value}€"

# stacked: control each segment individually
echo -e "Q1 100|50|30\nQ2 120|60|40" | chartscii -K -F '{value:0}↑{value:1}↓{value:2}' -I red green blue

Stacked bars

Three input formats, one renderer. Auto colors kick in if you don't pass -I.

echo -e "Q1 100|50|30\nQ2 120|60|40\nQ3 90|70|50" | \
  chartscii -I red green blue -J Frontend Backend DevOps -K

JSON form with per-segment color overrides:

chartscii examples/example-stacked-color-overrides.json -I marine pink purple -k pastel

Animation

Add -e to any chart to animate it. Bar charts grow from zero; line / step / scatter / candlestick / status reveal left-to-right.

seq 1 30 | chartscii -e -X easeOut -W 1500

| Flag | Default | Description | |---|---|---| | -e / --animate | false | Turn animation on | | -W / --animate-duration | 1000 | Total duration in ms | | -Z / --animate-fps | 60 | Frames per second | | -X / --animate-easing | easeOut | linear, easeIn, easeOut, easeInOut | | -Q / --animate-step | — | Step size 0–1 (overrides FPS when set) |

Recipes & shell helpers

A handful of pipelines worth keeping around. Drop these into your .bashrc / .zshrc:

# Bigger directories first, full terminal width
alias dirsize='du -sh */ | sort -rh | chartscii -w auto -c auto -t "Directory Sizes"'

# Code churn over the last 10 commits — green = additions, red = deletions
alias churn='git log --pretty=format:"%h" --numstat -10 | \
  awk "NF==3 {plus+=\$1; minus+=\$2} NF==1 {if(h) print h\" \"plus\"|\"minus; h=\$1; plus=0; minus=0} END {print h\" \"plus\"|\"minus}" | \
  chartscii -k pastel -I green red -c auto --no-sort'

# Files-by-extension across the repo
alias filetypes='find . -type f -not -path "*/node_modules/*" -not -path "*/.git/*" | \
  sed "s/.*\.//" | sort | uniq -c | sort -nr | head -10 | \
  chartscii -c "gradient(cyan,magenta)" -v'

# Memory hogs — top 5 processes by RSS
alias topmem='ps aux | sort -rn -k 6 | head -5 | \
  awk "{rss=\$6/1024; split(\$11,a,\"/\"); name=a[length(a)]; sub(/^-/,\"\",name); printf \"%s %d\n\", name, rss}" | \
  chartscii -c "gradient(green,red)" -k beach -v'

# Quick bar / vertical / percentage variants
alias chart='chartscii'
alias vchart='chartscii -o vertical'
alias pchart='chartscii -p'
alias autochart='chartscii -c auto'

A few showstoppers worth running once:

# Code churn — instant signal on whether a stretch was building or refactoring
git log --pretty=format:"%h" --numstat -10 | \
awk 'NF==3 {plus+=$1; minus+=$2} NF==1 {if(h) print h" "plus"|"minus; h=$1; plus=0; minus=0} END {print h" "plus"|"minus}' | \
chartscii -J -k pastel -I green red -c auto --no-sort

# Repo file distribution
find . -type f -not -path '*/.*' -not -path './node_modules/*' | \
sed 's/.*\.//' | sort | uniq -c | sort -nr | head -n 10 | \
chartscii -c "gradient(cyan,magenta)" -v

# File sizes from `ls -lh`
ls -lh | awk '{print $9" "$5}' | chartscii -c auto

Live dashboards with watch

watch -n 5 "du -sh */ | chartscii -c auto -t 'Directory Sizes'"
watch -n 1 "find . -name '*.ts' | wc -l | chartscii -t 'TS Files'"

Options reference

Chart type

| Short | Long | Default | Description | |---|---|---|---| | -Y | --type | bar | bar, line, step, scatter, candlestick, status | | -N | --variant | sharp | Step corner style: sharp or smooth | | -O | --points | false | Draw a marker at each point on step charts | | -H | --point-char | ● | Override the marker character | | -R | --rich-labels | true | Enable styl3 decorators (*bold*, %italic%, !underline!, @invert@) | | -g | --legend | false | Show a legend (multi-series line/step/scatter, candlestick, status) | | -B | --legend-position | top | top or bottom | | -M | --legend-align | left | left, center, right | | -U | --legend-values | — | Legend entry labels (space-separated) |

Display

| Short | Long | Default | Description | |---|---|---|---| | -t | --title | — | Chart title | | -T | --title-color | — | Title color (or gradient to match the chart gradient) | | -A | --title-align | left | left, center, right | | -D | --title-padding | — | CSS-style padding: n, v,h, or top,right,bottom,left | | -l | --labels | true | Display labels | | -C | --color-labels | true | Color the labels | | -p | --percentage | false | Display percentages | | -v | --value-labels | false | Show values on bars | | -P | --value-labels-prefix | — | Prefix (e.g. $, €) | | -V | --value-labels-floating-point | 2 | Decimal places | | -L | --label-format | — | Template with {label} placeholder | | -F | --value-label-format | — | Template with {value} (or {value:N} for stacked segments) |

Layout

| Short | Long | Default | Description | |---|---|---|---| | -o | --orientation | horizontal | horizontal or vertical | | -w | --width | 80 | Number, or auto for terminal width | | -h | --height | 1 (bar) / 10 (other) | Number, or auto for terminal height | | -b | --bar-size | — | Bar / candle / status-cell thickness | | -d | --padding | 1 | Space between bars / cells | | -E | --align-bars | — | top/center/bottom/justify (horizontal) or left/center/right/justify (vertical) |

Styling

| Short | Long | Default | Description | |---|---|---|---| | -c | --color | — | See the Colors table for accepted forms | | -k | --theme | — | Theme name (run --list-themes for the list) | | -z | --char | █ | Character used for bars | | -f | --fill | — | Opt-in fill character (▒ if flag alone, custom if value) | | -G | --fill-color | — | Fill color, or auto to match the chart gradient | | -S | --scale | auto | auto, relative, relative-zero, or fixed number |

Structure

| Short | Long | Default | Description | |---|---|---|---| | -n | --naked | false | Hide structure characters | | -x | --structure-x | ═ | Horizontal axis character | | -y | --structure-y | ╢ | Y-axis character | | -a | --structure-axis | ║ | Vertical axis character | | -q | --structure-bottom-left | ╚ | Bottom-left corner character |

Data

| Short | Long | Default | Description | |---|---|---|---| | -s | --sort | true for bar / false otherwise | Sort data | | -r | --reverse | false | Reverse the order |

Stacked bars

| Short | Long | Default | Description | |---|---|---|---| | -I | --stack-colors | — | Per-segment colors (space-separated) | | -J | --stack-labels | — | Per-segment labels | | -K | --stack-value-labels | false | Show segment values on bars (auto-enables -v) |

Animation

| Short | Long | Default | Description | |---|---|---|---| | -e | --animate | false | Turn animation on | | -W | --animate-duration | 1000 | Duration in ms | | -Z | --animate-fps | 60 | Frames per second | | -X | --animate-easing | easeOut | linear, easeIn, easeOut, easeInOut | | -Q | --animate-step | — | Step size 0–1 (overrides FPS when set) |

Utility

| Short | Long | Default | Description | |---|---|---|---| | -m | --list-themes | false | Print all available themes | | -? | --help | — | Show help | | | --version | — | Show version |

Notes

• Width on horizontal charts is exact: -w 80 produces output that fits in 80 columns, gutters and structure included.
• Width on vertical charts is approximate — for precise control, set -b (bar thickness) and -d 0 (no padding) explicitly.
• --sort defaults to off for non-bar chart types, since they're already ordered along the x-axis (time series, OHLC, host roster). Pass -s to opt in.

Built on chartscii — see that repo for the programmatic API.

License

MIT © Tal Hayut