Terminal Plotting with ggterm

Create plots using the CLI tool. Supports both built-in datasets and external files.

Built-in Datasets

ggterm includes datasets that work by name — no CSV files needed:

npx ggterm-plot iris sepal_length sepal_width species "Iris" point
npx ggterm-plot mtcars mpg hp cyl "Cars" point

IMPORTANT: When the user mentions iris, mtcars, or asks for demo/sample data, use these built-in names directly. Do NOT look for CSV files or generate data.

Live Plot Viewer

Start the companion viewer for high-resolution interactive plots:

npx ggterm-plot serve        # default port 4242
npx ggterm-plot serve 8080   # custom port

When serve is running, plots auto-display in the browser/Wave panel instead of ASCII art.

CLI Command

npx ggterm-plot <data> <x> <y> [color] [title] [geom]

Arguments:

• •data - Built-in dataset name (iris, mtcars) OR path to CSV/JSON/JSONL file
• •x - Column name for x-axis
• •y - Column name for y-axis (use - for histogram)
• •color - Column name for color (optional, use - to skip)
• •title - Plot title (optional, use - to skip)
• •geom - Geometry type: point (default), line, path, step, bar, col, histogram, freqpoly, density, boxplot, violin, ridgeline, joy, beeswarm, quasirandom, dumbbell, lollipop, waffle, sparkline, bullet, braille, calendar, flame, icicle, corrmat, sankey, treemap, volcano, ma, manhattan, heatmap, biplot, kaplan_meier, forest, roc, bland_altman, ecdf, funnel, control, scree, upset, dendrogram, area, ribbon, rug, errorbar, errorbarh, crossbar, linerange, pointrange, smooth, segment, curve, rect, tile, raster, bin2d, text, label, contour, contour_filled, density_2d, qq, hline, vline, abline

Inspect & Suggest (for external files)

npx ggterm-plot inspect <data.csv>
npx ggterm-plot suggest <data.csv>

Examples

Built-in data:

npx ggterm-plot iris sepal_length sepal_width species "Iris Dataset" point
npx ggterm-plot iris petal_length - species "Petal Length" histogram
npx ggterm-plot mtcars mpg hp cyl "MPG vs HP" point

External files:

npx ggterm-plot data.csv x y color "Title" point
npx ggterm-plot data.json date value - "Time Series" line

Workflow

1. •If user asks for iris/mtcars/demo data, use built-in dataset names directly
2. •For external files: run inspect to see columns, then suggest for recommendations
3. •Run the plot command
4. •Briefly describe what the plot shows

$ARGUMENTS

Geom Selection Guide

Common Plot Types

Scatter Plot

gg(data)
  .aes({ x: 'weight', y: 'height', color: 'species' })
  .geom(geom_point({ size: 2 }))

Line Chart

gg(data)
  .aes({ x: 'date', y: 'value', color: 'category' })
  .geom(geom_line())

Histogram

import { geom_histogram } from '@ggterm/core'

gg(data)
  .aes({ x: 'value' })
  .geom(geom_histogram({ bins: 20 }))

Box Plot

import { geom_boxplot } from '@ggterm/core'

gg(data)
  .aes({ x: 'group', y: 'value' })
  .geom(geom_boxplot())

Bar Chart

import { geom_bar } from '@ggterm/core'

gg(data)
  .aes({ x: 'category', fill: 'category' })
  .geom(geom_bar())  // Counts occurrences

Color and Styling

Color Scales

import { scale_color_viridis, scale_color_brewer } from '@ggterm/core'

// Viridis (perceptually uniform)
gg(data)
  .aes({ x: 'x', y: 'y', color: 'value' })
  .geom(geom_point())
  .scale(scale_color_viridis())

// ColorBrewer palettes
.scale(scale_color_brewer({ palette: 'Set1' }))  // Categorical
.scale(scale_color_brewer({ palette: 'Blues' })) // Sequential

Themes

import { themeDark, themeMinimal, themeClassic } from '@ggterm/core'

gg(data)
  .aes({ x: 'x', y: 'y' })
  .geom(geom_point())
  .theme(themeDark())      // Dark background
  // or .theme(themeMinimal())  // Clean, minimal
  // or .theme(themeClassic())  // Traditional

Faceting (Small Multiples)

import { facet_wrap, facet_grid } from '@ggterm/core'

// Wrap into grid
gg(data)
  .aes({ x: 'x', y: 'y' })
  .geom(geom_point())
  .facet(facet_wrap({ vars: 'category', ncol: 3 }))

// Grid by two variables
.facet(facet_grid({ rows: 'year', cols: 'region' }))

Scale Transformations

import { scale_x_log10, scale_y_sqrt } from '@ggterm/core'

gg(data)
  .aes({ x: 'population', y: 'gdp' })
  .geom(geom_point())
  .scale(scale_x_log10())
  .scale(scale_y_sqrt())

Layering Multiple Geoms

gg(data)
  .aes({ x: 'time', y: 'value' })
  .geom(geom_point({ alpha: 0.5 }))  // Points first
  .geom(geom_line())                  // Line on top
  .geom(geom_smooth({ method: 'loess' }))  // Trend line

Annotations

import { annotate_text, annotate_hline, annotate_rect } from '@ggterm/core'

gg(data)
  .aes({ x: 'x', y: 'y' })
  .geom(geom_point())
  .annotate(annotate_hline({ yintercept: 0, linetype: 'dashed' }))
  .annotate(annotate_text({ x: 10, y: 5, label: 'Important point' }))

Saving Plot Specifications

For reproducibility, save the PlotSpec alongside output:

import { writeFileSync } from 'fs'

const plot = gg(data).aes({ x: 'x', y: 'y' }).geom(geom_point())

// Get JSON-serializable specification
const spec = plot.spec()
writeFileSync('plot-spec.json', JSON.stringify(spec, null, 2))

// Render to terminal
console.log(plot.render({ width: 80, height: 24 }))

Render Options

plot.render({
  width: 80,           // Characters wide
  height: 24,          // Lines tall
  renderer: 'auto',    // 'braille' | 'block' | 'sixel' | 'auto'
  colorMode: 'truecolor'  // Use 'truecolor' for full color support
})

Quick Reference

For detailed examples, see examples/basic-plots.md.

All Available Geoms (68 total)

Point/line: geom_point, geom_line, geom_path, geom_step Bar: geom_bar, geom_col, geom_histogram, geom_freqpoly, geom_density Distribution: geom_boxplot, geom_violin, geom_ridgeline, geom_joy, geom_beeswarm, geom_quasirandom, geom_density_2d, geom_qq Comparison: geom_dumbbell, geom_lollipop Terminal-native: geom_waffle, geom_sparkline, geom_bullet, geom_braille Specialized: geom_calendar, geom_flame, geom_icicle, geom_corrmat, geom_sankey, geom_treemap, geom_volcano, geom_ma, geom_manhattan, geom_heatmap, geom_biplot Clinical/Statistical: geom_kaplan_meier, geom_forest, geom_roc, geom_bland_altman Statistical Diagnostics: geom_ecdf, geom_funnel, geom_control, geom_scree Set/Hierarchical: geom_upset, geom_dendrogram Area: geom_area, geom_ribbon Reference: geom_hline, geom_vline, geom_abline, geom_segment, geom_curve Text: geom_text, geom_label Error bars: geom_errorbar, geom_errorbarh, geom_crossbar, geom_linerange, geom_pointrange 2D/Tile: geom_tile, geom_raster, geom_bin2d, geom_rect, geom_contour, geom_contour_filled Other: geom_rug, geom_smooth

All Available Scales

Position: scale_x_continuous, scale_y_continuous, scale_x_log10, scale_y_log10, scale_x_sqrt, scale_y_sqrt, scale_x_reverse, scale_y_reverse, scale_x_discrete, scale_y_discrete

Color: scale_color_continuous, scale_color_discrete, scale_color_viridis, scale_color_brewer, scale_color_gradient, scale_color_gradient2, scale_fill_* (same variants)

Size: scale_size_continuous, scale_size_area, scale_size_radius

DateTime: scale_x_datetime, scale_y_datetime, scale_x_date, scale_y_date