chartroom 0.2.1

CLI tool for creating charts

Chartroom

CLI tool for creating charts from CSV, TSV, JSON, JSONL, or SQLite data using matplotlib. Designed to work well with Showboat.

Installation

pip install chartroom

Or:

uv tool install chartroom

Or run it directly with:

uvx chartroom

Demo

See the live demo document for examples of every chart type, input format, and style option with inline images. The demo was built using Showboat.

Usage

chartroom --help

Chart types

• chartroom bar - Bar chart (vertical, supports grouped bars)
• chartroom line - Line chart (supports multiple series)
• chartroom scatter - Scatter plot
• chartroom pie - Pie chart
• chartroom histogram - Histogram

Data input

Provide data as a file, via stdin, or from a SQLite query:

# From a CSV file (auto-detected)
chartroom bar data.csv

# Explicit format
chartroom bar --csv data.csv
chartroom bar --tsv data.tsv
chartroom bar --json data.json
chartroom bar --jsonl data.jsonl

# From stdin
cat data.csv | chartroom bar --csv

# From SQLite
chartroom bar --sql mydb.sqlite "SELECT name, count FROM items"

Column selection

Columns are auto-detected from common names (name/label/x for x-axis, value/count/y for y-axis), or specify explicitly:

chartroom bar --csv -x region -y revenue data.csv

Multiple y columns create grouped/overlaid series:

chartroom bar --csv -x region -y q1 -y q2 -y q3 data.csv

Output

By default, saves to chart.png (incrementing to chart-2.png etc. to avoid overwrites). Use -o to specify a path:

chartroom bar --csv data.csv -o sales.png

The full absolute path of the output file is printed to stdout.

Output format

Use -f / --output-format to control what is printed to stdout:

# Default: just the file path
chartroom bar --csv data.csv
# /path/to/chart.png

# Markdown image syntax
chartroom bar --csv data.csv -f markdown --alt "Sales by region"
# ![Sales by region](/path/to/chart.png)

# HTML img tag
chartroom bar --csv data.csv -f html --alt "Sales by region"
# <img src="/path/to/chart.png" alt="Sales by region">

# JSON with path and alt text
chartroom bar --csv data.csv -f json
# {"path": "/path/to/chart.png", "alt": "Bar chart of value by name — ..."}

# Just the alt text
chartroom bar --csv data.csv -f alt
# Bar chart of value by name — alice: 10, bob: 20, charlie: 15

When --alt is omitted, alt text is auto-generated from the chart title (if set) or from the chart type and data. Small datasets get all values listed; larger datasets get a summary with range and extremes.

Alt text generation

Chartroom automatically generates descriptive alt text for every chart, making output accessible to screen readers and useful in documentation. You can use --alt to provide your own alt text, or let chartroom generate it from the chart type and data.

The auto-generated alt text adapts to both chart type and dataset size:

• Bar, line, and scatter charts — Small datasets (6 rows or fewer) list every value (e.g. Bar chart of value by name — alice: 10, bob: 20, charlie: 15). Larger datasets summarize the count, range, and extremes (e.g. Bar chart of population by city. 10 points, ranging from 17118 (Dhaka) to 37400 (Tokyo)). Multiple y-columns are noted as additional series.
• Pie charts — Small datasets show each category with its percentage (e.g. Pie chart showing Rent (57%), Food (19%), Transport (10%), Other (14%)). Larger datasets list the top 3 categories by share.
• Histograms — Small datasets list all values. Larger datasets describe the distribution range (e.g. Histogram of 10 score values ranging from 76 to 95).

If a --title is set, it is prepended to the generated alt text (e.g. Team Scores. Bar chart of value by name — alice: 10, bob: 20, charlie: 15). The --alt option overrides this entirely with custom text. The alt text is embedded automatically when using -f markdown, -f html, or -f json output formats, or can be printed on its own with -f alt.

See the alt text demo for worked examples of every chart type and output format.

Styling

chartroom bar --csv data.csv --title "Sales" --xlabel "Region" --ylabel "Revenue" \
  --width 12 --height 8 --dpi 150 --style ggplot

Development

git clone https://github.com/simonw/chartroom
cd chartroom
uv run pytest