How to Display Job Dependency Graphs in ASCII Format Using the Probe CLI

Pass the --dag-ascii flag to the probe command to render a workflow's job dependencies as ASCII art directly in your terminal.

The Probe CLI from the linyows/probe repository converts YAML workflow definitions into console-ready dependency diagrams. This feature helps you visualize job execution order, needs relationships, and step composition before running your pipelines.

How Probe Renders ASCII Dependency Graphs

The ASCII visualization pipeline coordinates four architectural layers according to the linyows/probe source code:

1. CLI Flag Handling: In cmd/probe/main.go, the --dag-ascii flag is defined and routes execution to runDagAscii() when detected.
2. Probe Interface: probe.go implements the DagAscii() method, which loads the workflow file and delegates rendering.
3. Workflow Coordination: workflow.go contains RenderDagAscii(), which creates a DagAsciiRenderer instance and returns the formatted string.
4. Rendering Engine: The ascii-dag package performs the graphical logic. ascii-dag/dag_ascii.go implements NewDagAsciiRenderer() and applies Sugiyama-style level calculation to position nodes, draws connections using Unicode box-drawing characters, and formats job steps into boxed containers. The underlying ascii-dag/dag.go provides the generic directed-acyclic graph data structure with node/edge storage, cycle detection, and layout helpers.

This pipeline converts YAML jobs and their needs relationships into a hierarchical visualization. The renderer supports embedded action steps, automatic truncation for long identifiers, and dimmed filename hints for complex workflows.

Basic CLI Usage

To display a workflow's dependency graph, provide your YAML file path along with the --dag-ascii flag:

probe --dag-ascii my-workflow.yml

The output renders each job as a boxed node containing its enumerated steps, with dependency flows connecting parent jobs to their dependents:

╭─────────────────────╮      ╭─────────────────────╮
│  Build              │      │  Test               │
├─────────────────────┤      ├─────────────────────┤
│ ○ compile           │      │ ○ unit             │
│ ○ lint              │      │ ○ integration      │
╰───────┬─────────────╯      ╰───────┬─────────────╯
        │                          │
        ▼                          ▼
╭─────────────────────╮      ╭─────────────────────╮
│  Deploy             │      │  Notify             │
├─────────────────────┤      ├─────────────────────┤
│ ○ upload            │      │ ○ slack            │
│ ○ health‑check      │      │ ○ email            │
╰─────────────────────╯      ╰─────────────────────╯

Integrating ASCII Output in CI Scripts

Preview workflow structure before execution by incorporating the flag into automation scripts:

#!/usr/bin/env bash
set -e

WORKFLOW="ci-pipeline.yml"

# Print the ASCII DAG before execution

probe --dag-ascii "$WORKFLOW"

# Run the actual workflow

probe "$WORKFLOW"

This approach validates dependency logic visually before committing compute resources to the actual job run.

Programmatic Rendering in Go

For custom tooling or logging within Go applications, import the probe package and call DagAscii() directly:

package main

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

func main() {
	// Load a workflow file and render its DAG as ASCII
	p := probe.New("ci-pipeline.yml", false)

	graph, err := p.DagAscii()
	if err != nil {
		panic(err)
	}
	fmt.Println(graph)
}

This implementation uses the same method chain as the CLI: Probe.DagAscii() delegates to Workflow.RenderDagAscii(), which utilizes the DagAsciiRenderer from the ascii-dag package.

Summary

• Use --dag-ascii: Append this flag to any probe command followed by a workflow YAML path to generate ASCII art output in your terminal.
• Architecture: The feature spans cmd/probe/main.go (CLI entry), probe.go (public API), workflow.go (coordination), and the ascii-dag package (rendering engine).
• Visual Features: Output includes boxed job nodes with step lists, dependency connectors using box-drawing characters, Sugiyama-style hierarchical layout, and support for embedded actions with truncation.
• Integration Options: Available via direct command line execution, shell scripting for CI validation, or native Go API calls through the Probe.DagAscii() method.

Frequently Asked Questions

What file format does Probe require for workflow definitions?

Probe consumes YAML workflow files that define jobs and their needs dependencies, similar to GitHub Actions syntax. The parser in probe.go extracts job names, step definitions, and dependency relationships to build the directed acyclic graph structure rendered by the ASCII engine.

Can I customize the appearance of the ASCII dependency graph?

The rendering behavior is controlled through ascii-dag/dag_options.go, which exposes configuration options for layout modes and crossing-reduction passes. While the CLI flag uses default settings, programmatic access through DagAsciiRenderer allows adjustment of rendering parameters like node spacing and connection styles.

How does Probe handle complex workflows with circular dependencies?

The ascii-dag/dag.go implementation includes cycle detection within its generic DAG data structure. If your workflow YAML contains circular needs references, the graph builder identifies the cycle during the layout calculation phase and returns an error before rendering, preventing infinite loops in the dependency resolver.

Is the ASCII output suitable for CI/CD log viewing?

Yes, the ASCII output uses standard Unicode box-drawing characters that render correctly in modern CI log viewers including GitHub Actions, GitLab CI, and CircleCI. The visual hierarchy and step enumeration make it ideal for pre-execution validation logs, pull request descriptions, or documentation generation.

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