How to Create a Terminal or CLI-Window Variant of a Diagram Using the Instagit Diagram-Design Skill

Add the --format terminal or --format ansi flag to the insta diagram export command to render any supported diagram as ANSI text directly in your shell.

The Diagram-Design repository (cathrynlavery/diagram-design) is an Instagit skill that generates diagrams from Mermaid, Drawio, or Python-defined objects. When you need to create a terminal or CLI-window variant of a diagram, the skill exposes a text-only rendering path that prints ANSI-colored output to stdout, eliminating the need for external image viewers.

Registering the export-diagram Command and Format Flag

The CLI entry point is defined in [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md). This file registers the export-diagram command and configures argument parsing for the skill.

The command accepts a --format (or -f) flag. The default value is svg, but you can pass terminal or ansi to request a text-only rendering. An optional --width flag lets you constrain the output, for example --width 80.

Extracting Mermaid and Drawio Sources

Before rendering, the skill normalizes the input file into an internal diagram model. Depending on the source type, it invokes one of two extractor scripts located under skills/diagram-design/scripts/:

• mermaid_extract.py – parses Mermaid code into the internal model.
• drawio_extract.py – extracts diagram XML from Drawio files.

Both scripts feed the same unified representation into the downstream renderer, so switching between graphical and terminal output does not require re-parsing the source.

Generating a Terminal or CLI-Window Variant via ANSI Conversion

The core skill definition in [skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) declares the rendering pipeline and required libraries, including Rich, cairosvg, and lxml.

For graphical output, the skill calls standard SVG/PNG generators. For terminal output, it switches to the Rich library (rich.console.Console) and converts SVG geometry into a raster of ANSI characters and colors.

This conversion logic lives in [scripts/render-canonical-screenshots.py](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/render-canonical-screenshots.py), specifically in the svg_to_ansi helper. The function maps vector paths to a grid of characters, producing standard ANSI escape sequences that any modern terminal—Linux, macOS, Windows Terminal, or the VS Code integrated terminal—can display natively.

Practical Usage Examples

Run the following commands to generate terminal-friendly diagrams from your source files:

# Export a Mermaid diagram as a terminal rendering

insta diagram export my-diagram.mmd --format terminal

# Export a Drawio file as a terminal rendering with a custom width

insta diagram export diagram.drawio --format terminal --width 80

Because the output is plain text with ANSI codes, you can pipe it into shell scripts, redirect it to CI logs, or embed it in documentation generators without additional image assets.

Summary

• The export-diagram command in commands/export-diagram.md provides the --format flag to select output type.
• Supported text formats are terminal and ansi, while the default is svg.
• Source files are parsed by mermaid_extract.py or drawio_extract.py into a shared internal model.
• The svg_to_ansi helper in scripts/render-canonical-screenshots.py leverages the Rich library to convert SVG geometry into colored ANSI characters.
• Final output prints to stdout, making it portable across terminals and automation pipelines.

Frequently Asked Questions

What file types can I convert to a terminal diagram?

The Diagram-Design skill supports Mermaid (.mmd) and Drawio (.drawio) files through skills/diagram-design/scripts/mermaid_extract.py and drawio_extract.py. Both parsers feed the same rendering backend, so any supported source can be emitted as a terminal variant by adding --format terminal.

Do I need an image viewer to see the output?

No. When you pass --format terminal or --format ansi, the skill emits standard ANSI escape codes directly to stdout. Any modern terminal emulator—including Linux consoles, macOS Terminal, Windows Terminal, and the VS Code integrated terminal—can render the colored text without an external image viewer.

Can I control the width of the terminal output?

Yes. The export-diagram command accepts a --width flag. For example, insta diagram export file.drawio --format terminal --width 80 constrains the ASCII grid to 80 columns, which is useful for embedding diagrams in narrow console windows or log files.

Where is the ANSI conversion logic implemented?

According to the cathrynlavery/diagram-design source code, the conversion is handled by the svg_to_ansi function inside scripts/render-canonical-screenshots.py. This routine uses the Rich library to transform SVG vector paths into a grid of colored characters.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}