ggterm-plot

name: ggterm-plot description: Create terminal data visualizations using Grammar of Graphics. Use when plotting data, creating charts, graphing, visualizing distributions, or when the user mentions plot, chart, graph, histogram, scatter, boxplot, or visualize. allowed-tools: Bash(npx:ggterm-plot*), Read

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
npx ggterm-plot airway log2FoldChange padj gene "DESeq2 Results" volcano
npx ggterm-plot lung time status sex "Lung Survival" kaplan_meier

IMPORTANT: When the user mentions iris, mtcars, airway, lung, 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, histogram, boxplot, bar, violin, density, area, etc.

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