Trellis CLI Reference

The trellis binary renders Mermaid diagrams to SVG, PNG, HTML, ASCII, and Draw.io. It reads from a file or stdin, and writes to a file or stdout.

Installation

Homebrew (macOS and Linux) 

brew tap trellis-lab/trellis
brew trust trellis-lab/trellis
brew install trellis

Homebrew 6.0+ requires trusting third-party taps before their formulae can load. If you skip brew trust and see Error: Refusing to load formula ... from untrusted tap, run brew trust trellis-lab/trellis and retry the install.

winget (Windows) 

winget install TrellisLab.Trellis

Binary download

Platform File
macOS (Apple Silicon) trellis-vX.Y.Z-aarch64-apple-darwin.tar.gz
macOS (Intel) trellis-vX.Y.Z-x86_64-apple-darwin.tar.gz
Linux x86_64 trellis-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
Windows x86_64 trellis-vX.Y.Z-x86_64-pc-windows-gnu.zip

Download from the releases page, extract, and add trellis to your PATH.

Docker 

docker pull trellislab/trellis-cli:latest

See Docker usage.

Quick start 

trellis render diagram.mmd -o diagram.svg

Open diagram.svg in any browser or embed it in documentation.

Command reference

render

Render a single diagram.

trellis render <input> -o <output> [-f <format>] [--config <path>]

Pass - as <input> to read from stdin.

Examples:

# Render to SVG (default format)
trellis render input.mmd -o output.svg

# Render to PNG
trellis render input.mmd -o output.png

# Render to interactive HTML
trellis render input.mmd -o output.html -f html

# Render to ASCII (terminal preview)
trellis render input.mmd -o output.txt -f ascii

# Render to Draw.io (editable .mxfile)
trellis render input.mmd -o output.drawio -f drawio

# Render from stdin
echo "flowchart LR
  A --> B --> C" | trellis render - -o diagram.svg

# Render with custom config
trellis render input.mmd -o output.svg --config trellis.toml

render-batch

Render all .mmd files in a directory.

Commercial feature. render-batch requires a valid Trellis license. See Licensing.

trellis render-batch <input-dir> -o <output-dir>

Example:

trellis render-batch ./diagrams -o ./output

All .mmd files in ./diagrams are rendered to ./output using the same filename with a .svg extension.

validate

Parse a diagram and check for syntax errors — no render output produced.

trellis validate <input>

Example:

trellis validate input.mmd

Exits with code 0 on success, non-zero on error.

anonymize

Replace the text of a diagram with random characters so you can attach it to a bug report without exposing confidential names. Ids, labels, descriptions, class members, ER attributes, comments and the frontmatter title become random characters of the same length and character class. The same word always maps to the same replacement, so connections stay intact. Syntax, structure and styling are kept, so the result still reproduces layout and routing problems.

Commercial feature. anonymize requires a valid Trellis license. See Licensing.

trellis anonymize [input] [-o <output>] [--seed <n>]

Examples:

trellis anonymize input.mmd -o anonymized.mmd
trellis anonymize input.mmd -o anonymized.mmd --seed 42   # reproducible output
cat input.mmd | trellis anonymize - > anonymized.mmd
  • Reads stdin and writes stdout when no input or output is given.
  • Supports flowchart, class, ER, C4 and architecture diagrams; other types are rejected.
  • The result is re-parsed and compared with the input; if the structure differs, nothing is written.
  • Errors report line and column only, never diagram text.
  • %% trellis commands and %%{init}%% directives are copied unchanged, and text width is only approximated. Review the output before sharing it.
  • Exits with code 1 for invalid or unsupported diagrams, 2 for other failures (including a missing license).

license

Manage your Trellis license on this device. Required for commercial features such as render-batch and anonymize.

# Activate this device (consumes one seat)
trellis license activate --license-key YOUR_KEY

# Show current status and device instance
trellis license status

# Deactivate this device (frees the seat)
trellis license deactivate

The key is resolved in priority order: --license-key KEY > TRELLIS_KEY in a .env file in the working directory > TRELLIS_KEY environment variable. See Licensing for details and the subscribe link.

Flags

Flag Description
-o <path> Output file path
-f <format> Output format: svg (default), png, html, ascii, drawio
--config <path> TOML config file

Output formats

Pick a format with -f. Each one targets a different use case:

Format Purpose
svg Publication-ready vector — embed in web, Markdown, docs sites
png Raster image for slide decks, presentations, tools without SVG support
html Self-contained interactive viewer — explore large diagrams in a browser
ascii Terminal preview and AI-agent workflows — lowest token cost
drawio Editable .mxfile to hand-tweak in draw.io / Confluence

SVG

Scalable vector graphic. Embeds directly in HTML, Markdown, and documentation sites. Renders crisply at any size.

PNG

Rasterized image. Use for presentations, slide decks, and tools that don’t support SVG.

HTML

Self-contained interactive file. No server or internet connection required. Open in any browser to:

  • Click a node to highlight it, all connected edges, and its neighbours.
  • Click an edge to highlight it and its two endpoint nodes.
  • View an inspector panel with incoming/outgoing edge labels, neighbour names, and (for C4 diagrams) node descriptions.
  • Click a tag in the legend to highlight all tagged nodes and their edges; the legend shows tag counts.
  • Search nodes by name.
  • Pan and zoom with mouse drag and scroll wheel; use the minimap to navigate large diagrams.
  • Toggle between light and dark themes.
  • Click the background or close button to deselect.

ASCII

UTF-8 box-drawing diagram using Unicode characters (─ │ ┌ ┐ └ ┘ ▶ ▼). Node positions and edge paths match the SVG layout. Useful for terminal preview and AI-agent workflows — significantly lower token cost than SVG or HTML.

ASCII output is in development and disabled by default in pre-built binaries.

Draw.io

Editable .mxfile you can open directly in draw.io, Confluence, or the VS Code draw.io extension. Rendering is diagram-type-aware:

  • Flowchart — nodes as draw.io shapes with orthogonal routed edges
  • Class diagram — UML containers with typed relationship arrows
  • ER diagram — table stencils with crow’s-foot notation
  • C4 diagram — C4-styled shapes, colours, and boundary containers

Themes

Theme Description
default Default Trellis theme
paper Light, print-friendly
blueprint Technical blueprint style
dark Dark background
midnight Deep dark with accent colors
forest Green-toned

Set the theme via a config file:

# trellis.toml
theme = "paper"

Configuration

Create a trellis.toml file and pass it with --config:

trellis render input.mmd -o output.svg --config trellis.toml

Example config:

# Colour theme: default, paper, blueprint, dark, midnight, forest
theme = "paper"

# Inspector panel layout for HTML output: Landscape (default) or Portrait
html_orientation = "Landscape"

# C4 diagram node spacing in pixels: horizontal and vertical gap (default: 120, 80)
c4_gap_x = 120.0
c4_gap_y = 80.0

# C4 boundary stroke style: dashed (true, default) or solid (false)
c4_boundary_dashed = true

# Markdown label wrapping width in pixels (default: 200.0; 0.0 disables)
markdown_wrap_width = 200.0

# Anonymous usage ping — set to false to opt out (default: true)
telemetry = true

See Telemetry for what is collected and how to opt out.

Docker usage

The trellislab/trellis-cli image (Docker Hub, linux/amd64 and linux/arm64) wraps the CLI binary: arguments after the image name are passed to trellis. Mount the current directory to /data:

# Pull the image
docker pull trellislab/trellis-cli:latest

# Render to PNG (free)
docker run --rm -v "$(pwd):/data" trellislab/trellis-cli:latest render input.mmd -o output.png

# Render to SVG (requires a license key)
docker run --rm -v "$(pwd):/data" -v trellis-license:/root/.config/trellis -e TRELLIS_KEY \
  trellislab/trellis-cli:latest render input.mmd -o output.svg

-e TRELLIS_KEY passes the key from your shell environment. A key is activated on first use, which uses one seat; the trellis-license volume keeps that activation, so later runs don’t activate (and use a seat) again.

Stdin usage

Pass - as the input path to read diagram source from stdin:

echo "flowchart LR
  A --> B --> C" | trellis render - -o diagram.svg

Useful in shell pipelines and CI scripts.

Supported diagram types

  • Flowchart
  • Class diagram
  • Entity-relationship (ER)
  • C4 architecture diagram
  • Architecture (architecture-beta)

© Trellis Lab. Mermaid diagrams that actually look good.