Simple ASCII Chart

Simple ASCII Chart is a TypeScript package for generating ASCII charts in your terminal. It supports multi-dimensional input data, multi-series, custom colors, and formatters to make your data visualization customizable and visually engaging.

Interactive Demo

With color for multiple lines:

With colored area:

With axis positioning:

Installation

Install globally:

npm install -g simple-ascii-chart-cli

Or add it as a project dependency:

yarn add simple-ascii-chart-cli

Then use it in your project:

import plot from 'simple-ascii-chart';

const graph = plot(input, settings);
console.log(graph);

Playground

Try the interactive playground to create and customize graphs online.

API Endpoint

Generate charts programmatically by sending a POST request to the API endpoint with your input data:

curl -d input='[[1,2],[2,3],[3,4]]' -G https://simple-ascii-chart.vercel.app/api

Or as a URL parameter:

https://simple-ascii-chart.vercel.app/api?input=[[1,2],[2,3],[3,4]]&settings={"width":50}

CLI Usage

Run the CLI by passing your data and desired options:

simple-ascii-chart --input '[[1, 2], [2, 3], [3, 4]]' --title "Sample Chart"

Compatibility alias: simple-ascii-chart-cli is also available.

CLI Options

| Option | Alias | Type | Description | |-------------------|-------|----------|-------------------------------------------------------------------------------------------------------| | --input | -i | string | Inline input payload (JSON by default). | | --input-file | | string | Read static input from a file path. | | --format | | string | Static input format: json, csv, tsv, space. Auto-detected when omitted. | | --delimiter | | string | Custom delimiter for delimited static input. | | --header | | boolean | Treat first delimited row as a header row. | | --x-col | | string | X selector for delimited input (1-based index or header name). | | --y-col | | string | Y selector for delimited input (1-based index or header name). | | --stream | | boolean | Enable streaming mode and read newline-delimited samples from stdin. | | --window | | number | Keep only the latest N stream samples. Default: 60. | | --refresh-ms | | number | Redraw throttle in milliseconds. Default: 200. | | --rate | | boolean | Treat streamed values as counters and plot per-second rates. | | --series | | number | Stream series count (1 or 2). | | --passthrough | | boolean | Forward streamed stdin lines to stdout while plotting. | | --plot-output | | string | Plot destination stream: stdout or stderr. | | --options | -o | string | Additional plot settings as JSON. | | --width | -w | number | Plot width. | | --height | -h | number | Plot height. | | --title | -t | string | Plot title. | | --xLabel | | string | X axis label. | | --yLabel | | string | Y axis label. | | --mode | | string | Graph mode: line, point, bar, horizontalBar. | | --color | -c | array | ANSI colors for plot elements. | | --axisCenter | | array | Axis center coordinates (--axisCenter 0 0). | | --yRange | | array | Y range (--yRange 0 100). | | --showTickLabel | | boolean | Show axis tick labels. | | --thresholds | | array | JSON object/array string or tokenized JSON objects ('{"y":2}', '[{"y":2}]', '{"y":2}' '{"x":3}'). | | --points | | array | JSON object/array string or tokenized JSON objects ('{"x":1,"y":2}', '[{"x":1,"y":2}]'). | | --legend | | string | Legend settings in JSON format. | | --formatter | | string | Axis formatter function string. | | --lineFormatter | | string | Line formatter function string. | | --symbols | | string | Custom symbols in JSON format. | | --debugMode | | boolean | Enable chart engine debug mode. | | --fillArea | | boolean | Fill plot area. | | --hideXAxis | | boolean | Hide the x axis. | | --hideYAxis | | boolean | Hide the y axis. | | --verbose | | boolean | Print stack/details for parse/runtime errors. |

Static stdin example (no --input needed):

printf '1 1\n2 4\n3 9\n' | simple-ascii-chart --format space --title "stdin plot"

Threshold example:

simple-ascii-chart --input '[[1,1],[2,2],[3,3]]' --thresholds '{"y":2,"color":"ansiRed"}'

Points example:

simple-ascii-chart --input '[[1,1],[2,1],[3,1]]' --points '[{"x":2,"y":3,"color":"ansiGreen"}]'

Debug mode example:

simple-ascii-chart --input '[[1,1],[2,2],[3,3]]' --debugMode true

Live CPU Chart

Stream CPU samples directly into the chart.

Input formats accepted by --stream:

• NUMBER (x-axis uses sample time; default labels are elapsed like +0s, +1s)
• X,Y

macOS one-liner (top-based):

while true; do top -l 1 | awk -F'[, %]+' '/^CPU usage:/ {print $3+$6}'; sleep 1; done | simple-ascii-chart --stream --window 60 --height 10 --yRange 0 100 --title "CPU usage %"

Linux one-liner (vmstat-based):

vmstat 1 | awk 'NR>2 {print 100-$15}' | simple-ascii-chart --stream --window 60 --height 10 --yRange 0 100 --title "CPU usage %"

Live Network Bandwidth Chart

Stream network bandwidth (Mbps) into the chart.

macOS one-liner (default interface, total rx+tx):

IFACE=$(route -n get default 2>/dev/null | awk '/interface:/{print $2}'); PREV=$(netstat -ib -I "$IFACE" | awk 'NR>1 {sum+=$7+$10} END {print sum}'); while true; do sleep 1; CUR=$(netstat -ib -I "$IFACE" | awk 'NR>1 {sum+=$7+$10} END {print sum}'); awk -v c="$CUR" -v p="$PREV" 'BEGIN {printf "%.2f\n", (c-p)*8/1000000}'; PREV="$CUR"; done | simple-ascii-chart --stream --window 60 --height 10 --yRange 0 1000 --title "Network Mbps (rx+tx)"

Linux one-liner (default interface, total rx+tx):

IFACE=$(ip route | awk '/default/ {print $5; exit}'); PREV_RX=$(cat /sys/class/net/$IFACE/statistics/rx_bytes); PREV_TX=$(cat /sys/class/net/$IFACE/statistics/tx_bytes); while true; do sleep 1; CUR_RX=$(cat /sys/class/net/$IFACE/statistics/rx_bytes); CUR_TX=$(cat /sys/class/net/$IFACE/statistics/tx_bytes); awk -v cr="$CUR_RX" -v pr="$PREV_RX" -v ct="$CUR_TX" -v pt="$PREV_TX" 'BEGIN {printf "%.2f\n", ((cr-pr)+(ct-pt))*8/1000000}'; PREV_RX="$CUR_RX"; PREV_TX="$CUR_TX"; done | simple-ascii-chart --stream --window 60 --height 10 --yRange 0 1000 --title "Network Mbps (rx+tx)"

API Reference

Input Data

The input data should be a two-dimensional array. For a single series, provide an array of [x, y] coordinates:

const input = [
  [1, 1],
  [2, 4],
  [3, 8],
];

For multiple series, nest each series inside the main array:

const input = [
  [
    [1, 1],
    [2, 4],
    [3, 8],
  ],
  [
    [1, 2],
    [2, 3],
    [3, 5],
  ],
];

Settings

The plot appearance can be customized with the settings parameter, which accepts the following options:

• color: Array of colors for multiple series, or a single color for one series.
• width: Customizes plot width.
• height: Customizes plot height.
• axisCenter: Sets axis center, default is bottom-left.
• formatter: Formats axis labels. Accepts a Formatter function.
• lineFormatter: Customizes line appearance.
• title: Adds a title above the plot.
• xLabel: Sets label for x-axis.
• yLabel: Sets label for y-axis.
• thresholds: Adds thresholds with optional color.
• fillArea: If true, fills the area below each line.
• hideXAxis: Hides the x-axis if true.
• hideYAxis: Hides the y-axis if true.
• symbols: Customizes symbols for chart, axis, and background.

Example Usage

Create and display a simple plot with a title:

plot(
  [
    [1, 2],
    [2, 4],
    [3, 6],
  ],
  { title: 'Sample Data', width: 10, height: 6 }
);

Output:

Sample Data
   ▲
  6┤  ┏━
   │  ┃
  4┤  ┃
  2┤━━┛
   └─▶
    1 2 3

Plot with Multiple Series and Colors

plot(
  [
    [
      [1, 1],
      [2, 4],
      [3, 9],
    ],
    [
      [1, 3],
      [2, 6],
      [3, 3],
    ],
  ],
  { color: ['ansiRed', 'ansiBlue'], width: 15, height: 7 }
);

Examples

This README includes various examples with plots for titles, multi-series data, axis labels, area filling, custom symbols, and more.

For any questions or additional details, see the documentation.

Support

If this project helps you, consider supporting my open-source work:

Buy me a coffee