mermaid-ascii draws your Mermaid graph with box characters, and never truncates it

Three ways in: a file, a pipe, and a web server

The CLI reads a Mermaid file, reads standard input, or serves a web interface, and the three paths share the same renderer.

The file path takes a path directly:

mermaid-ascii --file test.mermaid

The same file can be passed with -f, which is the form used in most of the README's later examples. It can also read Mermaid text from standard input with no flag:

cat test.mermaid | mermaid-ascii

The web mode is a subcommand rather than a flag, with its own port:

docker run -p 3001:3001 mermaid-ascii web --port 3001

Installation has three routes. A release binary is fetched by querying the GitHub releases API with curl and filtering on the archive name, then unpacking the tarball. Building from source is git clone, cd, go build. Nix is the third, with nix build producing the binary under result/bin/.

The Docker path is the most convenient for scripting, and the image supports the stdin form directly, which is how you pipe a diagram definition in without mounting a file:

echo 'graph LR
A-->B-->C' | docker run -i mermaid-ascii -f -

The -f - form means the path is a dash, that is standard input, which is what makes it composable in a shell pipeline.

Spacing flags control how much room a graph takes

Two flags govern the geometry, and both exist because a rendered diagram is often wider than the terminal.

-x increases horizontal spacing, so the gaps between boxes and the length of the horizontal connectors grow:

mermaid-ascii --file test.mermaid -x 8

-p increases the box padding, growing the cell itself so a two-character label sits in a wider frame. Both are independent, so a diagram can be spread out horizontally without making every box taller.

That combination matters more than it sounds. Tightening -x can reduce horizontal whitespace and make a wide diagram more likely to fit the available terminal width.

The layout direction comes from the Mermaid source itself rather than from a flag. A file declaring graph LR renders left to right and one declaring graph TD renders top down, with the same command. That is the right division: the diagram's own header describes its shape, and the CLI describes the terminal.

Edge labels are carried through, including the pipe syntax. An edge written as B -->|example| D puts the word example on the connector.

Edge types beyond the plain arrow

The default connector is the solid arrow, but the tool covers the flowchart edge vocabulary rather than only that one form.

The README lists -.-> as dotted, ==> as thick, --- as open with no arrowhead, --o as a circle head and --x as a cross head. Each renders with its own line character, so a thick edge is drawn with a heavy horizontal rule while a dotted edge uses a different vertical glyph, and the cross head appears as a small mark at the target.

That is what makes the tool usable on a real diagram rather than a toy one. Sequence diagrams use solid arrows for requests and a dotted style for responses, and the Docker example in the README shows a sequenceDiagram rendered with two different connector styles for Alice and Bob's two messages.

The mermaid-ascii name is therefore slightly misleading about scope: sequence diagrams render too, since the README's Docker example demonstrates one, even though the width and layout flags are described in terms of graphs and flowcharts. The --max-width documentation says explicitly that the flag affects only graph and flowchart diagrams, which tells you what the layout code was written against.

max-width refuses to cut anything

The width handling is the most carefully specified behaviour in the README, and the rule it enforces is simple: content is never wrapped, truncated, cropped, or removed.

The flag takes either a positive number of terminal columns or the word auto:

mermaid-ascii --file test.mermaid --max-width 30
mermaid-ascii --file test.mermaid --max-width auto

auto detects stdout's terminal width and requires an interactive terminal, which means it will not do what you want in a piped context. Invalid and non-positive values are rejected rather than silently ignored.

When a graph exceeds the limit, rendering is retried with compact spacing, specifically paddingX=1 and paddingY=1. If that fits, the CLI notes that compact spacing was used. If it does not fit, it warns. Either way the diagram is complete.

That behaviour is the right call for a tool whose output often ends up in a log or a ticket: a diagram that silently loses a node is worse than one that overflows and tells you. The cost is that --max-width does not remove content; it retries with compact spacing and warns if the complete graph still does not fit.

The ASCII flag exists for logs, and it changes more than it looks

The default output uses box drawing characters for the frames and arrows for the connectors. The --ascii flag swaps all of that for plain ASCII:

cat test.mermaid | mermaid-ascii --ascii

Under that flag the frames become plus signs and pipes and the arrows become > and v, with the connectors built from hyphens. The resulting diagram is less pretty and considerably more portable.

That matters in three places people actually hit: a CI log viewer that does not handle Unicode, a terminal configured with a Latin-1 locale, and any pipeline that captures output into a file that will be diffed or grepped.

The width flag interacts with this too, since a plain-ASCII diagram is typically one column narrower or wider than the box drawing version depending on the glyph. If you are combining --ascii with --max-width auto in a script, test it rather than assuming the two compose.

The README's example output for --ascii also shows the arrowheads rendered as v for the downward connector and > for the horizontal one, which is what makes the ASCII form readable at a glance.

Cobra, Gin and a container that runs as a non-root user

The dependency list explains the two halves of the program. spf13/cobra is the CLI framework, which is where the web subcommand and the completion generation come from, and gin-gonic/gin serves the web interface. sirupsen/logrus handles logging, mattn/go-runewidth measures character display width, and gookit/color is present for terminal colour, which is what lets the web output and the diagram share a rendering path.

The go.mod requires Go 1.21, while the container builds on golang:1.25-alpine with CGO disabled, which produces a static binary.

The Dockerfile is careful about the runtime. The final stage is alpine:latest with ca-certificates, and it creates a dedicated mermaid group and user at uid 1000 rather than running as root. The binary goes to /usr/local/bin, the templates directory is copied alongside it and chowned to that user, and the container declares USER mermaid before the entrypoint. Port 3001 is exposed, matching the web mode default.

Because CGO is off and the user is unprivileged, the image is a reasonable base for running the web interface as a service. Development is handled by .air.toml with a Makefile dev target, and tests run through go test ./... -v with a Dockerfile.test for running them in a container.

There is also a PKGBUILD at the root for Arch, and the Makefile's install target installs bash completions into /usr/share/bash-completion/completions when that directory exists.

Editorial conclusion

mermaid-ascii earns a place in any workflow where a Mermaid file already exists as the source of truth, since it renders the same text you commit without a browser and without a rendering service in between. It is the wrong tool for sequence diagrams of any size, for anyone whose terminal cannot render box drawing characters, and for use in a pipeline that expects machine-readable output. Before depending on it in a script, use the --ascii flag so the output survives a plain log, and pass --max-width auto rather than assuming the default width matches your terminal, since the tool refuses to wrap content and will warn instead.

Frequently asked questions

Official sources

1. AlexanderGrooff/mermaid-ascii on GitHub
2. License: MIT
3. Project website
4. README
5. Releases