CLI that turns a CSV or JSON file into a chart — PNG by default, SVG or a self-contained HTML page on request. Charts come from Observable Plot: Plot defaults for styling, with custom color palettes as the one option.
npm install -g pingplotOr run from source (Node 18+, pnpm):
pnpm install
pnpm linkprintf 'month,traffic\nJan,10\nFeb,25\nMar,18\nApr,40\n' > report.csv
pingplot --data report.csv --mark bar --x month --y trafficWrites report.png next to the data file and prints the path. The chart type
comes from --mark; match your data to a type in catalog.md.
| Flag | Meaning |
|---|---|
--data <file> |
CSV or JSON input (.json = JSON, anything else = CSV) |
--mark <type> |
chart type: bar, line, area, dot, donut, box, heatmap, rule, funnel, sparkline |
--x <field> |
x channel (a field name in the data) |
--y <field> |
y channel |
--format <fmt> |
png | svg | html (default png) |
--color-range <hex,…> |
ordered colors → the color scale's range |
--size <preset> |
output size: default | doc (1200×800) |
--background <color> |
white | transparent (default white) |
--interactive |
hover tooltips — html only; png/svg stay static |
--spec <file> |
a full Plot options object instead of inline flags |
- png (default) — rendered server-side and rasterized.
- svg — the raw chart as a well-formed SVG file.
- html — a self-contained page that loads Plot from the CDN and renders in
the browser, so it needs a network connection.
--interactiveadds hover tooltips here; png/svg never include them.
Plot defaults everywhere — no theming. --color-range is the only
customization, and it maps straight to the color scale's range, so it works
for categorical, sequential, diverging, or cyclical scales:
pingplot --data report.csv --mark bar --x month --y traffic --color-range "#1d4ed8,#0f766e,#b45309"For a reusable branded chart, put the palette in a spec file instead.
For charts that will sit inside a document and print or export to PDF,
--size doc (1200×800) fills a letter/A4 content column and stays crisp.
--size default leaves Plot's own sizing alone. --background sets the
PNG/SVG background to white (default) or transparent — the donut scales with
size too.
A spec file is a JSON Plot options object — the way to build a complex chart or
a branded one, with colors baked in. Marks are named by Plot constructor; data
can live in the file or come from --data:
{
"data": [{ "month": "Jan", "traffic": 10 }],
"marks": [{ "type": "barY", "x": "month", "y": "traffic", "fill": "month" }],
"color": { "range": ["#1d4ed8", "#0f766e"] }
}pingplot --spec chart.jsonSpec files render the same chart as equivalent inline flags. Donut is the one
type a spec file can't express (Plot has no donut mark — pingplot draws it with
d3-shape), so donut is inline flags only.
catalog.md lists every chart type with the data shape it expects, the Plot marks behind it, and when to reach for it.
pingplot builds one JSON-serializable chart description — the data, the marks
(named by Plot constructor), and plot options — and renders it two ways:
server-side with Plot in jsdom for PNG and SVG, or embedded in a self-contained
HTML page that rebuilds the same chart in the browser. Inline flags and
--spec files both produce a description, so the two render paths can't drift.
Donut is the exception: Plot has no donut mark, so pingplot draws it with
d3-shape.
pnpm testThe suite covers parsing, loading, spec building, all three output formats, the client-side HTML script, and a catalog loop that renders every chart type from a committed fixture.