termaid renders Mermaid diagrams as Unicode text, in the terminal or from Python

The problem is that Mermaid normally needs a browser

The README states the reason for the project in one paragraph, and it is a reason that only makes sense once you have tried it. Mermaid is good for documentation, but rendering it usually means spinning up a browser or calling an external service. termaid exists so a diagram can be rendered over SSH, in CI logs, inside TUI apps, or anywhere a Python environment is available.

The author also names the two tools it set out to complement, mermaid-ascii in Go and beautiful-mermaid in TypeScript, and says plainly that neither offers a native Python library you can import and call directly. That is the gap termaid fills, and it explains the shape of the project: a Python package with an importable render function, not a wrapper around a browser or a service.

The package metadata confirms the shape. The project name is termaid, the version is 0.9.1, the license field is MIT, and requires-python is 3.9 or later, with classifiers for Python 3.9 through 3.13. The console environment classifier and the Development Status :: 3 - Alpha classifier are the two that matter for a reader deciding what to expect.

There is a hosted option as well. The README points to termaid.com with a try it online link, so the same rendering is available in a browser for people who do not want to install anything. The Python package and the web service are separate things, and only the package is what the rest of this review covers.

Eighteen diagram types, and what each one looks like when flattened

The supported list in the README names eighteen diagram types: flowcharts, sequence, class, ER, state, block, git, gantt, architecture, pie, treemap, mindmap, timeline, kanban, quadrant, XY chart, user journey and packet.

What makes the list worth reading is the vocabulary each type accepts, because that is where a renderer either supports a diagram properly or fakes it. The flowchart section lists every direction, LR, RL, TD or TB, and BT, thirteen node shapes from the plain rectangle through the rounded, diamond, stadium, subroutine, circle, double circle, hexagon, cylinder, asymmetric, parallelogram and trapezoid forms, and the `@{shape}` syntax for the rest. Edge styles cover solid, dotted, thick, bidirectional, circle endpoint, cross endpoint, labelled and variable length arrows.

The styling and structure support goes further than the diagram type. There are classDef, style and linkStyle directives, a `:::className` suffix for applying one, nested subgraphs with cross-boundary edges and per-subgraph direction overrides, `%%` comments, `;` line separators, Markdown labels in backticks, and the `&` operator for `A & B --> C`.

The sequence diagram section covers the four message types, solid and dashed arrow and line, plus participant, actor and alias declarations. The class diagram handles inheritance, composition, aggregation, association, dependency and realization relationships, and member visibility with the usual plus, minus, hash and tilde prefixes. The ER diagram covers the four cardinality forms, solid and dashed line styles, and attributes with type, name, keys such as PK, FK and UK, and comments.

That coverage is what separates a real renderer from a diagram-shaped approximation, and it is the reason to read the README rather than the feature bullet.

Terminal width is a hard constraint, so compaction is progressive

The feature list says terminal-aware, auto-fits diagrams to terminal width with progressive compaction. That phrase carries most of the engineering, and it is the one thing a browser renderer never has to solve.

A Mermaid graph is laid out in two dimensions, and a terminal is a fixed rectangle of characters. When a graph is wider than the window, something has to give. The README describes the answer as progressive compaction, which means the diagram is narrowed in stages rather than all at once, so the structure survives as long as possible and only then loses detail.

The alternative designs are all worse in one direction or another. Clipping the right edge loses nodes without saying so. Refusing to render a wide graph makes the tool useless for exactly the diagrams people draw, since a layered flowchart with eight steps is naturally wide. Scaling to fit means shrinking the text to nothing.

The related feature is the ASCII fallback. The README lists it as working on any terminal, even the most basic ones, which means the renderer can emit plain box characters instead of the Unicode ones. The two shapes in the README's own output make the difference visible: a flowchart node drawn with Unicode box drawing and rounded corners, against a version drawn with parentheses for the stadium shape. The first is prettier and depends on the terminal's font and locale, the second renders anywhere.

For a tool whose whole purpose is output you cannot control, the terminal is the environment, and how it degrades matters more than how it looks at its best.

Installing is three commands and the Python API is one import

The install section covers pip, Homebrew and a no-install path:

pip install termaid

brew install termaid

uvx termaid diagram.mmd

That last one is the version to try first if you want to see the output before committing to an install, since uvx runs the tool in a throwaway environment.

The Python side is a single import, and the README notes the zero dependencies claim in the feature list as pure Python with nothing to install beyond the package itself:

from termaid import render

print(render("graph LR\n  A --> B --> C"))

The two extras add the nicer surfaces. Coloured output needs the rich extra and the render_rich function:

# Colored output (requires: pip install termaid[rich])
from termaid import render_rich
from rich import print as rprint

rprint(render_rich("graph LR\n  A --> B", theme="terra"))

And a Textual widget needs the textual extra:

# Textual TUI widget (requires: pip install termaid[textual])
from termaid import MermaidWidget

widget = MermaidWidget("graph LR\n  A --> B")

The optional dependency group in pyproject.toml confirms the mapping: rich is rich 13.0 or newer, textual and tui are both textual 0.40 or newer, and the dev group is pytest 7.0 or newer with pytest-snapshot. The console entry point is registered as termaid, mapped to termaid.cli:main, and the wheel packages src/termaid.

Six colour themes are available, default, terra, neon, mono, amber and phosphor, and mono is worth knowing about because it is the one that survives being piped into a log file or a CI viewer that interprets escape sequences badly.

The CLI reads files, stdin and entire Markdown documents

The command line interface is where the pipe-friendliness claim shows up, and the README's quick start lists the forms:

termaid diagram.mmd
echo "graph LR; A-->B-->C" | termaid
termaid diagram.mmd --theme neon
termaid diagram.mmd --ascii
termaid --markdown README.md          # draw every 

mermaid block in a document gh pr view 42 | termaid --markdown ```

Reading from stdin is what makes the tool compose with shell pipelines, and the last two lines show the extension of that idea. The --markdown flag takes a document and draws every mermaid block inside it, and it reads from stdin too, so a pull request body can be piped in from gh pr view. For a reviewer reading a diff, that turns a diagram in a pull request description into something visible in the terminal without opening a browser.

The theme and ascii flags are per invocation, so the same diagram can be rendered in colour for a terminal and in plain ASCII for a log file, without maintaining two source files.

There is a subtlety worth flagging: the markdown mode looks for fenced mermaid blocks, which is the Mermaid convention in documentation, so a document using a different fence style will not be picked up. The README does not document that edge case, so if you rely on the feature it is worth checking against your own files.

Where termaid is the wrong tool

The obvious boundary is output quality. termaid produces characters, not pixels, so it cannot produce the styled, accessible SVG that the official Mermaid tooling produces. If the destination is a README on a public repository, a documentation site, a slide deck or a PDF, the character rendering is the wrong medium, and the ASCII output looks noticeably rough compared with a rendered diagram.

The second limit is layout fidelity. Terminal rendering works in a grid of characters, and Mermaid's own layout engine computes positions in a continuous two-dimensional space. termaid reproduces that structure in a monospaced grid, which means relative placement, arrow routing and node spacing are approximations. The README's own examples show the shape of the result, and the horizontal spacing in a wide graph is not what Mermaid would produce.

The third limit is the diagram type list. Eighteen types is broad, but Mermaid itself keeps adding syntax, and the README's coverage of each type is a snapshot of what the project supports today rather than a promise about the next release. The project is marked alpha at version 0.9.1, so behaviour may change between minor versions.

The fourth is that the tool is deliberately narrow in the other direction too. It renders Mermaid, it does not read other diagram formats, and it does not produce images. There is no export to PNG or SVG mentioned anywhere in the README, which is both the weakness and the point.

The alternative in the same space is mermaid-ascii in Go or beautiful-mermaid in TypeScript, and the README is explicit about the difference: neither offers a native Python library you can import and call directly. If you are writing a Python application and want to draw a diagram at runtime, termaid is the one with a library API. If you want a static binary with no Python dependency, mermaid-ascii is the one to compare against, and if you want a JavaScript toolchain, beautiful-mermaid is.

A fast release line and a permissive licence

The maintenance picture is current. The last push was on 2026-10-18 and the repository is not archived, and the release history shows v0.9.1 on 2026-10-18, v0.9.0 on 2026-09-15 and v0.8.0 on 2026-07-29. Three releases in a quarter is a project that is shipping.

The repository layout backs that up. There is a src/ directory, a tests/ directory with pytest configured through testpaths in pyproject.toml, a uv.lock for reproducible dependency resolution, plus CHANGELOG.md, CONTRIBUTING.md and a LICENSE file at the root, and a .github/ directory for the workflows. The build backend is hatchling, and the project publishes a wheel that packages src/termaid.

The licence is MIT, recorded in both the metadata and the LICENSE file. MIT is a permissive grant with no copyleft obligation on code you build with it, which matters for a rendering library you might vendor into a closed source tool. That is a licensing note rather than legal advice.

The one thing to keep in mind alongside the release cadence is the alpha classifier. The project is at 0.9.1 and declares itself alpha, so the public API is not promised to be stable, and a tool you depend on for CI output is one where a sudden change in rendering could affect how your own logs read. Pinning a version is the obvious precaution.

Editorial conclusion

Adopt termaid if you need Mermaid diagrams to appear in terminals, CI logs, SSH sessions or TUI applications, since it ships zero runtime dependencies and both a CLI and an importable Python API. Do not adopt it as a replacement for the official Mermaid renderer when you need pixel-perfect output for documentation or presentations, because the ASCII and Unicode output is the entire product. Verify first that the diagram types you use are on the supported list, that your terminal renders the box-drawing characters the renderer emits, and that the width compaction does not mangle the graph at the column limit you run in.

Frequently asked questions

Official sources

1. fasouto/termaid on GitHub
2. License: MIT
3. Project website
4. README
5. Releases