asciigraph: ASCII line graphs in Go with no chart dependencies

What asciigraph solves, and who it is for

Most charting libraries assume a canvas, a browser or an image encoder. A Go service that prints a status line every few seconds has none of those. asciigraph fills that gap: it takes a []float64 and returns a string of box-drawing characters that looks like a line chart when printed. The README describes it as a "Go package to make lightweight ASCII line graphs", and the repository lists no dependencies beyond the standard library; go.mod declares only the module path and go 1.11.

The audience is narrow and specific. It is a Go developer who already has numbers in memory and wants them visible in a terminal: a benchmark loop, a queue depth counter, a memory reading, a sine wave in an example program. It is not aimed at someone producing a chart for a document, and it is not aimed at a non-Go user, because the library itself is imported as a Go package. The CLI in cmd/asciigraph widens that slightly, since it can read numbers from standard input, but the primary artifact is the package.

How Plot turns a slice of float64 into a graph

The API is a single call with functional options. asciigraph.Plot(data) returns a string; the options are applied in order and change scaling, width, height, colors and labels. The README's basic example plots fifteen values and shows the result rendered with a Y-axis column, a value label per row, and a vertical bar separating labels from the plot area.

The rendering model has consequences worth stating plainly. The Y-axis labels are derived from the data range, so the top and bottom rows correspond to the minimum and maximum of the series rather than to round numbers, unless you constrain them. LowerBound and UpperBound exist for exactly that, and the threshold example uses LowerBound(0) and UpperBound(100) to keep a CPU percentage chart anchored to its real domain. Width and Height control the character grid, not pixels, so the resolution is coarse by construction: a 10-row graph has ten vertical positions for the entire data range.

Multi-series support comes from PlotMany, which takes [][]float64. The README's example passes two slices of different lengths, so the series do not have to be aligned. Colors are set with SeriesColors and named constants such as Red, Yellow, Green and Blue. A separate path, SeriesColorGradient, colors each point by its own value along a palette, with HeatmapSpectrum offered as a built-in cool-to-warm option. Threshold coloring sits on top of both: ColorAbove and ColorBelow take a color and a threshold, ColorAbove colors points strictly greater than its value and ColorBelow strictly less, and the README states that ColorAbove wins when both match the same point. That precedence rule is the kind of detail that decides whether an alert chart reads correctly, and it is documented rather than left to guesswork.

Installing asciigraph and drawing your first graph

For library use, the README gives one command. It fetches the latest module version into your module cache and records it in go.mod.

go get -u github.com/guptarohit/asciigraph@latest

A minimal program then imports the package and prints the returned string. The data below is the README's basic example, fifteen values that produce a graph with a peak of 10 and a low of 2.

package main

import (
    "fmt"
    "github.com/guptarohit/asciigraph"
)

func main() {
    data := []float64{3, 4, 9, 6, 2, 4, 5, 8, 5, 10, 2, 7, 2, 5, 6}
    fmt.Println(asciigraph.Plot(data))
}

Running it prints a text chart with a 10.00 row at the top and a 2.00 row near the bottom. If you want a labelled horizontal axis, add XAxisRange and XAxisTickCount; the README notes the tick count defaults to 5 and has a minimum of 2. The formatter option changes only the label text, not the plotted shape, which is why the README's GiB example can show 70.00 GiB and 2.00 GiB on the same axis.

graph := asciigraph.Plot(data,
    asciigraph.Height(5),
    asciigraph.Width(45),
    asciigraph.YAxisValueFormatter(func(v float64) string {
        return fmt.Sprintf("%.2f GiB", v/1024/1024/1024)
    }),
)

The CLI is a separate install. The README assumes $GOPATH/bin is on your PATH, then installs the command from cmd/asciigraph. A container image is also published, and the repository's Dockerfile builds a static binary from cmd/asciigraph/main.go and copies it into a scratch image with the binary as the entry point.

go install github.com/guptarohit/asciigraph/cmd/asciigraph@latest

Once installed, the CLI reads values from standard input. The README's threshold example pipes seq output through it and sets two thresholds with the -ca and -cb flags, each taking a color and a value.

seq 1 100 | asciigraph -h 10 -ca red,80 -cb green,25

That command should print a ten-row graph where points above 80 appear red and points below 25 appear green.

Where asciigraph stops being the right choice

The output is text, and that is a hard boundary rather than a stylistic one. There is no export to SVG, PNG or HTML in the README, and no interactive mode. If the chart has to go into a slide, a PDF or a web page, asciigraph produces something you would have to screenshot, and a plotting library that writes an image file is the better fit.

The character grid also limits what a reader can take from the graph. Two series that differ by a small amount over a large range will overlap or merge, because there are only as many vertical positions as you asked for with Height. The README's own examples use well-separated data, and the multi-series example deliberately uses series of different lengths and shapes. Nothing in the documentation describes collision handling for near-identical series, so that is a case to check against your own data before you build a feature on it.

Color is another constraint that the documentation only partly addresses. The colored output depends on ANSI escape sequences, and the README does not document a no-color mode or a way to detect a non-terminal destination. A graph written to a file or a log aggregator may therefore contain escape codes. The README is silent on this point, so if your output path is not a terminal, test it rather than assume.

Finally, the project is a library, not a monitoring system. It renders the numbers you hand it and keeps no history. If you need retention, alerting rules or a query language, asciigraph sits at the wrong layer entirely.

asciigraph compared with a terminal dashboard like Termdash

Search traffic around asciigraph often lands near Termdash, and the two solve different problems. Termdash is a terminal dashboard framework: it owns the screen, lays out widgets in a grid, and redraws them on a timer. asciigraph owns nothing. It returns a string, and you decide where that string goes, whether that is fmt.Println, a log line, or a buffer you write to a socket.

The practical difference is lifecycle. A Termdash application runs an event loop and manages a canvas; adopting it means adopting its model of the terminal. asciigraph has no loop and no state between calls. You can call Plot inside a function that runs once and exits, which is what makes it usable in a test helper or a one-shot CLI. The cost of that simplicity is everything a dashboard gives you for free: no layout, no keyboard input, no refresh scheduling, no widgets other than the line chart.

A second comparison is with charting libraries that render to an image. Those give you axes, fonts and export formats, and they need a rendering backend. asciigraph trades all of that for the ability to print into any text stream, including one with no graphical capability at all.

Maintenance, releases and what the BSD-3-Clause licence means here

The repository is not archived, and the last push was on 2026-06-21, the same day as the v0.10.0 release. Releases are frequent and small: v0.8.1 on 2026-03-08, v0.9.0 on 2026-03-28, then v0.10.0. The presence of release-please-config.json, .release-please-manifest.json, CHANGELOG.md and .goreleaser.yml in the repository root indicates an automated release and changelog flow, which lowers the cost of tracking versions: the changelog is generated rather than hand-written.

Upgrade cost is low for the library itself. The public surface is a set of functions and options, and the README's examples use only exported names. go.mod declares go 1.11, so the module builds on old toolchains. The Dockerfile, however, pins golang:1.23-alpine as the builder image, so anyone building the container needs a newer Go than the module directive suggests. That mismatch is worth knowing before you wire the image into a pipeline.

The licence is BSD-3-Clause, which is permissive and includes a clause covering the use of contributor names for endorsement. For a library you vendor into a binary, that generally means keeping the copyright notice and licence text with the distribution. This is a description of the licence file, not legal advice; if your organisation has a policy on attribution, check it against LICENSE in the repository.

Editorial conclusion

Adopt asciigraph if you write Go and want a chart inside a terminal, a log line or a CI output, where an image file would be awkward. Do not adopt it if you need axes with real scales, interactivity, or output for a report or a web page; a plotting library that emits SVG or PNG is the wrong comparison, and asciigraph is the wrong tool for that job. Before you commit, verify two things in your own code: what Plot does with NaN values, since the colored-graph example relies on math.NaN() to break a series, and whether the default Y-axis formatting is enough or you need YAxisValueFormatter to label bytes or durations.

Frequently asked questions

Official sources

1. guptarohit/asciigraph on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases