Chart Image Generator
Generate PNG chart images from data using Vega-Lite. Perfect for headless server environments.
Why This Skill?
Built for Fly.io / VPS / Docker deployments:
- ✅ No native compilation - Uses Sharp with prebuilt binaries (unlike
canvas
which requires build tools)
- ✅ No Puppeteer/browser - Pure Node.js, no Chrome download, no headless browser overhead
- ✅ Lightweight - ~15MB total dependencies vs 400MB+ for Puppeteer-based solutions
- ✅ Fast cold starts - No browser spinup delay, generates charts in <500ms
- ✅ Works offline - No external API calls (unlike QuickChart.io)
Setup (one-time)
cd /data/clawd/skills/chart-image/scripts && npm install
Quick Usage
node /data/clawd/skills/chart-image/scripts/chart.mjs \
--type line \
--data '[{"x":"10:00","y":25},{"x":"10:30","y":27},{"x":"11:00","y":31}]' \
--title "Price Over Time" \
--output chart.png
Chart Types
Line Chart (default)
node chart.mjs --type line --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output line.png
Quantitative X-domain clamp
Useful when you want a fixed numeric or temporal window without editing Vega-Lite by hand:
node chart.mjs --type line \
--data '[{"minute":0,"value":12},{"minute":1,"value":18},{"minute":2,"value":14},{"minute":3,"value":20}]' \
--x-field minute --y-field value --x-type quantitative \
--x-domain 0,2 --title "First 3 Minutes" \
--output x-domain.png
Bar Chart
node chart.mjs --type bar --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output bar.png
Area Chart
node chart.mjs --type area --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output area.png
Histogram
Use this for numeric distributions instead of pre-binned bar charts:
node chart.mjs --type histogram \
--data '[{"value":12},{"value":18},{"value":19},{"value":24},{"value":31}]' \
--x-field value --x-title "Response Time (ms)" --y-title "Count" \
--bins 8 --tick-min-step-y 1 --x-label-angle -30 \
--output hist.png
Pie / Donut Chart
# Pie
node chart.mjs --type pie --data '[{"category":"A","value":30},{"category":"B","value":70}]' \
--category-field category --y-field value --output pie.png
Donut (with hole)
node chart.mjs --type donut --data '[{"category":"A","value":30},{"category":"B","value":70}]'
--category-field category --y-field value --output donut.png
Candlestick Chart (OHLC)
node chart.mjs --type candlestick \
--data '[{"x":"Mon","open":100,"high":110,"low":95,"close":105}]' \
--open-field open --high-field high --low-field low --close-field close \
--title "Stock Price" --output candle.png
Heatmap
node chart.mjs --type heatmap \
--data '[{"x":"Mon","y":"Week1","value":5},{"x":"Tue","y":"Week1","value":8}]' \
--color-value-field value --color-scheme viridis \
--y-label-overlap greedy \
--title "Activity Heatmap" --output heatmap.png
Multi-Series Line Chart
Compare multiple trends on one chart:
node chart.mjs --type line --series-field "market" \
--data '[{"x":"Jan","y":10,"market":"A"},{"x":"Jan","y":15,"market":"B"}]' \
--title "Comparison" --output multi.png
Stacked Bar Chart
node chart.mjs --type bar --stacked --color-field "category" \
--data '[{"x":"Mon","y":10,"category":"Work"},{"x":"Mon","y":5,"category":"Personal"}]' \
--title "Hours by Category" --output stacked.png
Volume Overlay (Dual Y-axis)
Price line with volume bars:
node chart.mjs --type line --volume-field volume \
--data '[{"x":"10:00","y":100,"volume":5000},{"x":"11:00","y":105,"volume":3000}]' \
--title "Price + Volume" --output volume.png
Sparkline (mini inline chart)
node chart.mjs --sparkline --data '[{"x":"1","y":10},{"x":"2","y":15}]' --output spark.png
Sparklines are 80x20 by default, transparent, no axes.
Options Reference
Basic Options
| Option | Description | Default |
|---|
--type
| Chart type: line, bar, area, point, histogram, pie, donut, candlestick, heatmap | line |
--data
| JSON array of data points | - |
--output
| Output file path | chart.png |
--title
| Chart title | - |
--width
| Width in pixels | 600 |
--height
| Height in pixels | 300 |
Axis Options
| Option | Description | Default |
|---|
--x-field
| Field name for X axis | x |
--y-field
| Field name for Y axis | y |
--x-title
| X axis label | field name |
--y-title
| Y axis label | field name |
--x-type
| X axis type: ordinal, temporal, quantitative | ordinal |
--x-domain
| Clamp/zoom the X scale with min,max
bounds for quantitative or temporal charts | auto |
--x-format
| Temporal X axis label format (d3-time-format, e.g. %b %d
, %H:%M
) | auto |
--x-sort
| X axis order: ascending, descending, or none (preserve input order) | auto |
--series-order CSV
| Explicit series/category order for multi-series and stacked legends (e.g. Critical,High,Medium
) | data order |
--x-label-limit PX
| Max pixel width for X axis labels before Vega truncates them | auto |
--y-label-limit PX
| Max pixel width for Y axis labels before Vega truncates them | auto |
--x-ticks N
| Target X-axis tick count for dense or sparse charts | auto |
--y-ticks N
| Target primary/left Y-axis tick count for dense or sparse charts | auto |
--bins N
| Histogram bin count (--type histogram
only) | Vega auto |
--tick-min-step N
| Minimum step between ticks on quantitative axes (great for counts / whole-number charts) | Vega auto |
--tick-min-step-x N
| Minimum step between ticks on quantitative X axes only | Vega auto |
--tick-min-step-y N
| Minimum step between ticks on quantitative Y axes only | Vega auto |
--x-label-angle N
| Rotate X-axis labels (for dense categories / timestamps) | -45 |
--y-label-angle N
| Rotate Y-axis labels (useful for horizontal bars / heatmaps) | 0 / Vega default |
--x-label-overlap MODE
| Force Vega X-axis overlap handling (parity
, greedy
, true
, false
) for crowded labels | Vega auto |
--y-label-overlap MODE
| Force Vega Y-axis overlap handling (parity
, greedy
, true
, false
) for crowded labels | Vega auto |
--y2-ticks N
| Target secondary/right Y-axis tick count for dual-axis and volume charts | auto |
--y-domain
| Y scale as "min,max" | auto |
--y-pad
| Add vertical padding as a fraction of range (e.g. 0.1
= 10%) | 0 |
Visual Options
| Option | Description | Default |
|---|
--color
| Line/bar color | #e63946 |
--dark
| Dark mode theme | false |
--svg
| Output SVG instead of PNG | false |
--font-family
| CSS font-family string for chart text/legend/title theming | Helvetica, Arial, sans-serif |
--title-align
| Title alignment: start
, middle
, end
| start |
--title-size N
| Title font size override in px | auto |
--subtitle-size N
| Subtitle font size override in px | auto |
--title-weight W
| Title font weight override (normal
, bold
, 100
-900
) | auto |
--subtitle-weight W
| Subtitle font weight override (normal
, bold
, 100
-900
) | auto |
--title-color
| Title text color override | theme text |
--subtitle-color
| Subtitle text color override | theme grid |
--grid-dash A,B
| Dash pattern for gridlines (for example 4,2
) | solid |
Font examples:
"Inter, Helvetica, Arial, sans-serif"
,
"Georgia, serif"
,
"JetBrains Mono, Consolas, monospace"
|
--no-points
| Hide point markers on line charts | false |
|
--line-width N
| Set line thickness in pixels for line charts | 2 |
|
--point-size N
| Set point marker size for line/point charts | 60 |
|
--bar-radius N
| Round bar corners in pixels for bar-based charts | 0 |
|
--color-scheme
| Vega color scheme (category10, viridis, etc.) | - |
|
--legend-columns N
| Wrap legend entries into N columns for crowded multi-series/pie charts | auto |
|
--legend-label-limit PX
| Max pixel width for legend labels before Vega truncates them | auto |
Alert/Monitor Options
| Option | Description | Default |
|---|
--show-change
| Show +/-% change annotation at last point | false |
--focus-change
| Zoom Y-axis to 2x data range | false |
--focus-recent N
| Show only last N data points | all |
--show-values
| Label min/max peak points | false |
--last-value
| Label the final data point value | false |
Multi-Series/Stacked Options
| Option | Description | Default |
|---|
--series-field
| Field for multi-series line charts | - |
--stacked
| Enable stacked bar mode | false |
--color-field
| Field for stack/color categories | - |
Candlestick Options
| Option | Description | Default |
|---|
--open-field
| OHLC open field | open |
--high-field
| OHLC high field | high |
--low-field
| OHLC low field | low |
--close-field
| OHLC close field | close |
Pie/Donut Options
| Option | Description | Default |
|---|
--category-field
| Field for pie slice categories | x |
--donut
| Render as donut (with center hole) | false |
Heatmap Options
| Option | Description | Default |
|---|
--color-value-field
| Field for heatmap intensity | value |
--y-category-field
| Y axis category field | y |
Dual-Axis Options (General)
| Option | Description | Default |
|---|
--y2-field
| Second Y axis field (independent right axis) | - |
--y2-title
| Title for second Y axis | field name |
--y2-color
| Color for second series | #60a5fa (dark) / #2563eb (light) |
--y2-type
| Chart type for second axis: line, bar, area | line |
--y2-format
| Right-axis format: percent, dollar, compact, integer, decimal4, or d3-format string | auto |
Example: Revenue bars (left) + Churn area (right):
node chart.mjs \
--data '[{"month":"Jan","revenue":12000,"churn":4.2},...]' \
--x-field month --y-field revenue --type bar \
--y2-field churn --y2-type area --y2-color "#60a5fa" --y2-format ".1f" \
--y-title "Revenue ($)" --y2-title "Churn (%)" \
--x-sort none --dark --title "Revenue vs Churn"
Volume Overlay Options (Candlestick)
| Option | Description | Default |
|---|
--volume-field
| Field for volume bars (enables dual-axis) | - |
--volume-color
| Color for volume bars | #4a5568 |
Formatting Options
| Option | Description | Default |
|---|
--y-format
| Y axis format: percent, dollar, compact, decimal4, integer, scientific, or d3-format string | auto |
--subtitle
| Subtitle text below chart title | - |
--hline
| Horizontal reference line: "value" or "value,color" or "value,color,label" (repeatable) | - |
Annotation Options
| Option | Description | Default |
|---|
--annotation
| Static text annotation | - |
--annotations
| JSON array of event markers | - |
Alert-Style Chart (recommended for monitors)
node chart.mjs --type line --data '[...]' \
--title "Iran Strike Odds (48h)" \
--show-change --focus-change --show-values --dark \
--output alert.png
For recent action only:
node chart.mjs --type line --data '[hourly data...]' \
--focus-recent 4 --show-change --focus-change --dark \
--output recent.png
Timeline Annotations
Mark events on the chart:
node chart.mjs --type line --data '[...]' \
--annotations '[{"x":"14:00","label":"News broke"},{"x":"16:30","label":"Press conf"}]' \
--output annotated.png
Temporal X-Axis
For proper time series with date gaps:
node chart.mjs --type line --x-type temporal \
--data '[{"x":"2026-01-01","y":10},{"x":"2026-01-15","y":20}]' \
--output temporal.png
Use
--x-type temporal
when X values are ISO dates and you want spacing to reflect actual time gaps (not evenly spaced).
Y-Axis Formatting
Format axis values for readability:
# Dollar amounts
node chart.mjs --data '[...]' --y-format dollar --output revenue.png
# → $1,234.56
Percentages (values as decimals 0-1)
node chart.mjs --data '[...]' --y-format percent --output rates.png
→ 45.2%
Compact large numbers
node chart.mjs --data '[...]' --y-format compact --output users.png
→ 1.2K, 3.4M
Crypto prices (4 decimal places)
node chart.mjs --data '[...]' --y-format decimal4 --output molt.png
→ 0.0004
Custom d3-format string
node chart.mjs --data '[...]' --y-format ',.3f' --output custom.png
Available shortcuts:
percent
,
dollar
/
usd
,
compact
,
integer
,
decimal2
,
decimal4
,
scientific
Chart Subtitle
Add context below the title:
node chart.mjs --title "MOLT Price" --subtitle "20,668 MOLT held" --data '[...]' --output molt.png
--subtitle
works across standard charts plus pie/donut, heatmap, candlestick, stacked, multi-series, volume-overlay, and dual-axis layouts.
Theme Selection
Use
--dark
for dark mode. Auto-select based on time:
- Night (20:00-07:00 local):
--dark
- Day (07:00-20:00 local): light mode (default)
Social Size Presets
Use
--output-size
when the chart is meant for a specific surface:
# Bluesky / OG-style landscape post
node chart.mjs --type line --data '[...]' --output-size bluesky --output bluesky-chart.png
Instagram / Threads portrait post
node chart.mjs --type line --data '[...]' --output-size portrait --output portrait-chart.png
Available presets include
twitter
,
discord
,
slack
,
linkedin
,
bluesky
(
bsky
alias),
youtube
,
instagram
,
portrait
,
story
,
thumbnail
,
wide
, and
square
.
Piping Data
echo '[{"x":"A","y":1},{"x":"B","y":2}]' | node chart.mjs --output out.png
Custom Vega-Lite Spec
For advanced charts:
node chart.mjs --spec my-spec.json --output custom.png
⚠️ IMPORTANT: Always Send the Image!
After generating a chart, always send it back to the user's channel.
Don't just save to a file and describe it — the whole point is the visual.
# 1. Generate the chart
node chart.mjs --type line --data '...' --output /data/clawd/tmp/my-chart.png
2. Send it! Use message tool with filePath:
action=send, target=<channel_id>, filePath=/data/clawd/tmp/my-chart.png
Tips:
- Save to
/data/clawd/tmp/
(persistent) not /tmp/
(may get cleaned)
- Use
action=send
with filePath
— thread-reply
does NOT support file attachments
- Include a brief caption in the message text
- Auto-use
--dark
between 20:00-07:00 Israel time
Updated: 2026-04-06 - added --y-label-angle
for crowded categorical/heatmap charts and documented per-axis label rotation; version bumped to 2.6.33
