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

> Visualize job dependencies with Probe CLI using the dag mermaid flag. Generate Mermaid flowcharts to easily understand workflow execution order and dependencies.

- Repository: [Tomohisa Oda/probe](https://github.com/linyows/probe)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/linyows/probe/blob/main/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:

```bash
probe --dag-mermaid example.yml

```

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

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

```

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

```markdown

```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`](https://github.com/linyows/probe/blob/main/cmd/probe/main.go).
- The rendering engine in [`dag_mermaid.go`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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.