charts-cli 📊

Chart generation CLI for agents.

Feed it an ECharts JSON config, get back SVG or PNG. No browser, no GUI, no fuss.

Examples

For Humans

You install it. Your agent does the rest.

Installation

npm install -g charts-cli

Setup

# Teach your agent how to use charts
charts onboard

This adds instructions to your CLAUDE.md or AGENTS.md file. Done.

Themes

Built-in themes: dark, vintage, or pass a path to a custom JSON theme file.

echo '{...}' | charts render --theme dark -o chart.png

For Agents

1. Get the Schema

# What chart types are available?
charts schema --list

# Get the schema for what you need
charts schema bar
charts schema xAxis
charts schema tooltip
charts schema              # Full EChartsOption (top-level keys)

Available types:

• Series: bar, line, pie, scatter, radar, funnel, gauge, treemap, boxplot, heatmap, candlestick, sankey
• Components: title, tooltip, grid, xAxis, yAxis, legend, dataZoom, visualMap, toolbox, dataset, radar-coord, polar, geo

2. Render

# From stdin
echo '{
  "xAxis": { "type": "category", "data": ["Mon", "Tue", "Wed"] },
  "yAxis": { "type": "value" },
  "series": [{ "type": "bar", "data": [120, 200, 150] }]
}' | charts render -o chart.png

# From file
charts render --config option.json -o chart.svg

Render Options

| Option | Description | |--------|-------------| | --config <file> | JSON file with ECharts option | | -o, --output <file> | Output file (default: stdout) | | -W, --width <n> | Width in pixels (default: 800) | | -H, --height <n> | Height in pixels (default: 400) | | --theme <name> | dark, vintage, or path to JSON theme | | --format <type> | svg or png (auto-detected from extension) |

Output

• No -o sends SVG to stdout (pipeable)
• -o chart.svg writes SVG
• -o chart.png or --format png writes PNG

FAQ

Q: Why not just have the agent write a Python script with matplotlib?

Because that's a whole runtime, dependencies, and 50 lines of code for a bar chart. This is one pipe.

Q: Why ECharts?

30+ chart types, deep customization, great docs, and agents already know the config format from training data. The schema command fills in the gaps.

Q: What if the agent generates invalid JSON?

ECharts is forgiving. Missing fields get defaults. The agent gets the chart (maybe not perfect) and can iterate.

Development

bun install
bun run src/main.ts --help

# Regenerate schemas from ECharts types
bun run generate:schema

License

MIT