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

> Display job dependencies as ASCII art in your terminal. Use the Probe CLI with the --dag-ascii flag to visualize workflows directly.

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

---

**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`](https://github.com/linyows/probe/blob/main/cmd/probe/main.go), the `--dag-ascii` flag is defined and routes execution to `runDagAscii()` when detected.
2. **Probe Interface**: [`probe.go`](https://github.com/linyows/probe/blob/main/probe.go) implements the `DagAscii()` method, which loads the workflow file and delegates rendering.
3. **Workflow Coordination**: [`workflow.go`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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:

```bash
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:

```bash
#!/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:

```go
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`](https://github.com/linyows/probe/blob/main/cmd/probe/main.go) (CLI entry), [`probe.go`](https://github.com/linyows/probe/blob/main/probe.go) (public API), [`workflow.go`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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`](https://github.com/linyows/probe/blob/main/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.