Super charge your command
line data wrangling

vcli helps you quickly visualize CSV data
from files, APIs, and other programs

Beta vcli is beta software, please report any issues you experience.

Motivation

Whether you're a data scientist, engineer, or data visualizer, you've probably run into a case where you want to quickly analyze and understand a dataset by calculating distributions of values, outliers, completeness, and other statistics.

vcli aims to integrate into existing command line workflows with support for piping in data, while also providing the richness & flexibility of browser-based visualizations.

Install

Installing via npm

  1. Install node.js via package manager or download, if you haven't already.

  2. Install the vcli package globally

$ npm install -g @vcli-org/vcli

Standalone Installer

A standalone installer is currently only available for Mac, contributions to add Windows support for adding Windows support) are welcomed.

Visit the releases page to find the latest installer for your system.

Usage

USAGE
  $ vcli [FILE]
  $ program | vcli

OPTIONS
  -h, --help           show CLI help
  -v, --version        show CLI version

  -x, --x-axis=x-axis  Column index/name to plot on x-axis of charts. For date fields you can specify an aggregate function like start_date:month
                       (supports day/month/year)

  -y, --y-axis=y-axis  Column index/name to plot on y-axis of charts. You can also specify an aggregate function like sales:sum (supports
                       count/min/max/sum/mean/median/p5/p95)

  --facet=facet        Column index/name that will be used to group data into separate charts
  --port=port          Port to run the local webserver on (default is 8888)

vcli does not store or send any of your data over the internet – everything takes place on your local machine.

Because it visualizes your data using a browser, it is not useful during remote sessions like ssh or other headless environments.

Examples

Launch "Overview" visualization with stats & distributions for all columns

$ vcli data.csv

Launch "Analysis" visualization with specified configuration

$ vcli -x date:month -y cases:sum --facet state data.csv

Pipe CSV data from an API into vcli

$ curl -s https://raw.githubusercontent.com/nytimes/covid-19-data/master/us-counties.csv | vcli

Pipe CSV data from another program into vcli

$ python my-csv-generator.py | vcli

Troubleshooting

Working with very large files

By default Node.js processes have 512mb of memory, if you are processing a very large file you could run into out of memory errors like the following:

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

You can increase this memory limit by prepending your vcli command with an extra option:

export NODE_OPTIONS="--max_old_space_size=8192" && vcli ...

The above command would allow the node process to use up to 8gb of memory while it's running.

Resources

If vcli isn't quite what you're looking for, you might like one of these browser-based visualizers:

And if you're looking for other complimentary command line data tools, check out these projects: