How to Display Job Dependency Graphs in Mermaid Format with Probe CLI

Probe CLI generates Mermaid flowcharts from workflow definitions using the --dag-mermaid flag to visualize job dependencies and execution order.

Probe is an open-source workflow engine written in Go that orchestrates jobs with complex dependency management. The tool includes a built-in capability to display job dependency graphs in Mermaid format, enabling you to visualize execution flows directly in your terminal or embed them in documentation. This feature is implemented through the DagMermaidRenderer component and exposed via both command-line and programmatic interfaces.

Using the --dag-mermaid CLI Flag

The simplest way to generate a Mermaid diagram is by passing the --dag-mermaid flag followed by your workflow YAML file. According to the source code in cmd/probe/main.go, the Cmd.parseArgs function recognizes this flag on lines 96-107 and sets the DagMermaid boolean on the command configuration.

When the flag is detected, the runDagMermaid() function (lines 59-66) executes the rendering pipeline and outputs the result to stdout.

Render a workflow file as Mermaid text:

probe --dag-mermaid example.yml

Redirect the output to a file for documentation or version control:

probe --dag-mermaid example.yml > workflow.mmd

Embed the output directly in a Markdown document using command substitution:

```mermaid
$(probe --dag-mermaid example.yml)

## Internal Implementation of the Mermaid Renderer

The rendering pipeline involves three core components defined in [`dag_mermaid.go`](https://github.com/linyows/probe/blob/main/dag_mermaid.go) and integrated via [`cmd/probe/main.go`](https://github.com/linyows/probe/blob/main/cmd/probe/main.go).

### Flag Parsing and Execution Path

1. **Argument parsing** – `Cmd.parseArgs` in [`main.go`](https://github.com/linyows/probe/blob/main/main.go) (lines 96-107) detects the `--dag-mermaid` flag and populates the `c.DagMermaid` field.
2. **Execution routing** – When `c.DagMermaid` is true, `runDagMermaid()` executes (lines 59-66), loading the workflow via `probe.New(c.WorkflowPath, c.Verbose)`.
3. **Output generation** – The workflow's `RenderDagMermaid()` method is called, and the resulting string is written to `c.outWriter` (stdout).

### DagMermaidRenderer Architecture

The `DagMermaidRenderer` struct traverses the `Workflow` object and constructs valid Mermaid syntax through the following process:

- **Job indexing** – Builds a `jobIDToIdx` map (lines 22-29) for O(1) lookup of job references.
- **ID sanitization** – The `sanitizeID()` function (lines 31-47) strips invalid characters from job and step identifiers to ensure Mermaid compatibility.
- **Graph construction** – Writes the `flowchart LR` header and creates a subgraph for each job containing its steps (lines 42-95).
- **Dependency mapping** – Traverses all `needs` relationships and writes edges between dependent nodes (lines 99-112).

### Workflow.RenderDagMermaid() Convenience Method

The `Workflow` struct provides `RenderDagMermaid()` as a public API that instantiates `NewDagMermaidRenderer` and returns the complete Mermaid string, handling all sanitization and formatting internally.

## Programmatic Usage in Go

You can generate Mermaid output directly within your Go applications without invoking the CLI. This is useful for building documentation generators or CI/CD reporting tools.

```go
package main

import (
    "fmt"
    "github.com/linyows/probe"
)

func main() {
    w := probe.New("example.yml", false)
    if err := w.Do(); err != nil {
        panic(err)
    }
    fmt.Println(w.RenderDagMermaid())
}

This approach uses the same DagMermaidRenderer internally, ensuring consistent output between programmatic and CLI usage.

Summary

• Use probe --dag-mermaid workflow.yml to generate Mermaid diagrams from the command line according to the implementation in cmd/probe/main.go.
• The rendering engine in dag_mermaid.go automatically sanitizes job IDs via sanitizeID() and constructs valid flowchart LR syntax with subgraphs for each job.
• Dependencies are mapped by traversing the needs relationships defined in your workflow YAML.
• Access the functionality programmatically through Workflow.RenderDagMermaid() for custom tooling and automation.
• Reference dag_mermaid_test.go for golden-file examples of expected Mermaid output patterns.

Frequently Asked Questions

What is the exact command to generate a Mermaid diagram with Probe?

Run probe --dag-mermaid your-workflow.yml. This invokes runDagMermaid() in cmd/probe/main.go (lines 59-66), which loads the workflow configuration and prints the Mermaid flowchart definition to stdout.

How does Probe handle invalid characters in job IDs for Mermaid syntax?

The DagMermaidRenderer implemented in dag_mermaid.go uses the sanitizeID() function (lines 31-47) to process job and step identifiers. This ensures node names conform to Mermaid's identifier requirements by removing or replacing characters that would break the diagram parsing.

Can I use the Mermaid rendering feature in my own Go application?

Yes. Import github.com/linyows/probe, initialize a workflow with probe.New(), execute w.Do() if needed, and call w.RenderDagMermaid() to obtain the Mermaid string directly. This bypasses the CLI entirely while using the same rendering logic.

Where can I find examples of the expected Mermaid output format?

The dag_mermaid_test.go file contains comprehensive unit and golden-file tests that demonstrate expected Mermaid output for various DAG topologies. These tests provide concrete examples of generated syntax including subgraph definitions and edge declarations.

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