npx chartli

chartli

CLI for rendering charts in terminals from numeric text data. chartli turns plain numbers into terminal charts. ascii, spark, bars, columns, heatmap, unicode, braille, svg.

Install

Run instantly:

npx chartli --help

Or install globally:

npm i -g chartli

Agent skill install

Install the repository skill for agents:

npx skills add ahmadawais/chartli

Quick start:

npx chartli
npx chartli --help

Usage

npx chartli [file] [options]

Usage: chartli [options] [file]

Render terminal charts from numeric data

Arguments:
  file                   Input file (reads from stdin if not provided)

Options:
  -v, --version          Output the version number
  -t, --type <type>      Chart type: svg, ascii, unicode, braille, spark, bars,
                         columns, heatmap (default: "ascii")
  -w, --width <number>   Chart width
  -h, --height <number>  Chart height
  -m, --mode <mode>      SVG mode: circles or lines (default: "circles")
  --x-axis-label <label> Title to render for the x-axis
  --y-axis-label <label> Title to render for the y-axis
  --x-labels <labels>    Comma-separated labels for x-axis ticks or row labels
  --series-labels <labels>
                         Comma-separated labels for plotted series or categories
  --data-labels          Show raw values near plotted data when supported
  --first-column-x       Treat the first numeric column as x labels instead of a
                         plotted series
  --help                 Display help for command

Labels and metadata

Use --x-axis-label and --y-axis-label to add axis titles.
Use --x-labels for explicit tick labels.
Use --series-labels to replace generic labels like S1 and C1.
Use --data-labels to print raw values on or near the plotted data where the renderer supports it.
Use --first-column-x when the first numeric column is a domain like day, month, or year.

With --first-column-x, chartli will:

use the first numeric column as x-axis labels
use the first header cell as the x-axis title when a header row exists
use the remaining header cells as series labels
use the second header cell as the y-axis title for common two-column data

Example:

pnpm chartli examples/assets/core-single-series.txt -t ascii -w 24 -h 8 --first-column-x --data-labels

pnpm chartli examples/assets/core-multi-series.txt -t columns -h 8 --first-column-x --series-labels sales,costs,profit --x-axis-label Metrics --y-axis-label Value --data-labels

Labeled chart examples

ASCII line with inferred axis labels and data labels

pnpm chartli examples/assets/weekly-signups.txt -t ascii -w 28 -h 8 --first-column-x --data-labels

        signups
    91 │                      ●   87
       │                     91    ●
       │            73
       │             ●   68
  66.5 │   58             ●
       │    ●   49
       │42       ●
    42 │●
       └────────────────────────────
        1   2    3   4    5   6    7
                    day

Columns with explicit axis titles and inferred series names

pnpm chartli examples/assets/weekly-metrics.txt -t columns -h 8 --first-column-x --x-axis-label Metrics --y-axis-label Count --data-labels

Count
 176     29     10


  █
  █
  █
  █
  █      ▓      ▒
  █      ▓      ▒
────────────────────
visits trials  paid
      Metrics

SVG with axes, x labels, and point labels

pnpm chartli examples/assets/weekly-signups.txt -t svg -m lines -w 320 -h 120 --first-column-x --data-labels | sed -n '/^<?xml/,$p' > examples/assets/output/weekly-signups-chart.svg

This writes examples/assets/output/weekly-signups-chart.svg.

Types

ascii
spark
bars
columns
heatmap
unicode
braille
svg

Example data files

examples/assets/core-single-series.txt
examples/assets/core-multi-series.txt
examples/assets/image-data.txt
examples/assets/image-single-series.txt
examples/assets/image-columns-variant.txt
examples/assets/weekly-signups.txt
examples/assets/weekly-metrics.txt

Image chart set (text diagrams)

ASCII Line

pnpm chartli examples/assets/image-data.txt -t ascii -w 24 -h 8

      day=●  sales=○  costs=◆  profit=◇
1.00 │                       ○
     │
     │             ◇         ◇
     │                  ◆    ●
0.50 │                  ●    ◆
     │    ◇    ◆   ●
     │         ○   ◆
0.00 │◇   ◆    ◇        ◇
     └────────────────────────

Sparklines

pnpm chartli examples/assets/image-data.txt -t spark

day    ▁▂▃▄▅▆
sales  ▁▄▂▇▅█
costs  ▁▂▄▃▆▅
profit ▁▄▂▇▂▇

Horizontal Bars

pnpm chartli examples/assets/image-data.txt -t bars -w 28

day    |███████████████████         | 0.67
sales  |▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓| 1.00
costs  |▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒             | 0.53
profit |░░░░░░░░░░░░░░░░░░░░░░░     | 0.83

Columns

pnpm chartli examples/assets/image-data.txt -t columns -h 8

         ▓
         ▓             ░
         ▓             ░
  █      ▓             ░
  █      ▓      ▒      ░
  █      ▓      ▒      ░
  █      ▓      ▒      ░
  █      ▓      ▒      ░
───────────────────────────
 day   sales  costs  profit

Columns (Variant)

pnpm chartli examples/assets/image-columns-variant.txt -t columns -h 8


         ▓             ░
  █      ▓             ░
  █      ▓             ░
  █      ▓      ▒      ░
  █      ▓      ▒      ░
  █      ▓      ▒      ░
───────────────────────────
 day   sales  costs  profit

Heatmap

pnpm chartli examples/assets/image-data.txt -t heatmap

    day sales costs profit
R01
R02 ░ ▒ ░ ▒
R03 ░ ░ ▒ ░
R04 ▒ ▓ ░ ▓
R05 ▒ ▒ ▓ ░
R06 ▓ █ ▒ ▓

Unicode Bars

pnpm chartli examples/assets/image-data.txt -t unicode

 day    sales   costs   profit
             █
           ▃ █             ▅ ▅
     ▃     █ █      ▃      █ █
    ▂█     █▆█      █▂     █ █
   ▂██   ▂ ███    ▂ ██   ▃ █ █
  ▁███   █ ███    █▁██   █ █ █
 ▁████   █▅███   ▁████   █▁█▁█
 █████   █████   █████   █████

Braille

pnpm chartli examples/assets/image-data.txt -t braille -w 16 -h 6

profit

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠀⠀⠀⠀⠀⠈
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⡀⠀⠀⠀⠀⠀⠁⠀⠀⠀⠀⠀⠁⠀⠀⠀

SVG Chart

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

<?xml version='1.0'?>
<svg xmlns='http://www.w3.org/2000/svg' width='650' height='120' version='1.1'>
  <polyline ... />
  <polyline ... />
  <polyline ... />
  <polyline ... />
</svg>

svg

Examples

All examples are data-file driven from examples/assets/.

Data files

examples/assets/core-single-series.txt
examples/assets/core-multi-series.txt
examples/assets/image-data.txt
examples/assets/image-single-series.txt
examples/assets/image-columns-variant.txt
examples/assets/weekly-signups.txt
examples/assets/weekly-metrics.txt
examples/assets/output/

Core commands

pnpm chartli examples/assets/core-single-series.txt -t ascii -w 24 -h 8
pnpm chartli examples/assets/core-multi-series.txt -t spark
pnpm chartli examples/assets/core-multi-series.txt -t bars -w 28
pnpm chartli examples/assets/core-multi-series.txt -t columns -h 8
pnpm chartli examples/assets/core-multi-series.txt -t heatmap
pnpm chartli examples/assets/core-multi-series.txt -t unicode
pnpm chartli examples/assets/core-single-series.txt -t braille -w 16 -h 6
pnpm chartli examples/assets/core-multi-series.txt -t svg -m lines -w 320 -h 120 | sed -n '/^<?xml/,$p' > examples/assets/output/core-chart.svg

Image commands

pnpm chartli examples/assets/image-data.txt -t ascii -w 24 -h 8
pnpm chartli examples/assets/image-data.txt -t spark
pnpm chartli examples/assets/image-data.txt -t bars -w 28
pnpm chartli examples/assets/image-data.txt -t columns -h 8
pnpm chartli examples/assets/image-columns-variant.txt -t columns -h 8
pnpm chartli examples/assets/image-data.txt -t heatmap
pnpm chartli examples/assets/image-data.txt -t unicode
pnpm chartli examples/assets/image-data.txt -t braille -w 16 -h 6
pnpm chartli examples/assets/image-data.txt -t svg -m lines -w 320 -h 120 | sed -n '/^<?xml/,$p' > examples/assets/output/image-chart.svg

Labeled commands

pnpm chartli examples/assets/weekly-signups.txt -t ascii -w 28 -h 8 --first-column-x --data-labels
pnpm chartli examples/assets/weekly-metrics.txt -t columns -h 8 --first-column-x --x-axis-label Metrics --y-axis-label Count --data-labels
pnpm chartli examples/assets/weekly-signups.txt -t svg -m lines -w 320 -h 120 --first-column-x --data-labels | sed -n '/^<?xml/,$p' > examples/assets/output/weekly-signups-chart.svg

Run grouped examples

pnpm run example:kitchen-sink
pnpm run example:image-set:kitchen-sink
pnpm run example:labeled:kitchen-sink
pnpm run example:all-kitchen-sink

Run all examples

Image-set chart run:

pnpm run example:image-set:kitchen-sink

Core + image run:

pnpm run example:all-kitchen-sink

License

Apache-2.0 by Ahmad Awais built with Command Code.

Chartli

Install / Use

README