The simplest way to use task-graph is to generate a Graphviz .dot file from your Taskfile:
task-graph Taskfile.yml --output taskfile.dot
This file can be rendered into an image using dot (a part of Graphviz):
dot taskfile.dot -Tpng -o taskfile.png
Alternatively, you can have task-graph invoke Graphviz for you — just pass --render-image with the desired file type:
task-graph Taskfile.yml --output taskfile.dot --render-image png
This produces both the .dot file and the rendered image in one step. The image file takes its name from the output file, with the extension replaced — so taskfile.dot becomes taskfile.png. You can use any format that Graphviz supports: png, svg, pdf, jpg, and more.
If dot is not on your system PATH, you can point task-graph at its location using the dotPath setting in your configuration file.
Understanding the graph
The graph shows two kinds of relationships between tasks:
Dependency edges (solid lines) represent tasks listed under deps: in your Taskfile. These are prerequisites — task A depends on task B, so B must complete before A can run.
Call edges (dashed lines, coloured blue by default) represent tasks invoked from the cmds: section using task: otherTask. These are direct invocations — task A explicitly calls task B as one of its steps.
Each node shows the task name and, where available, the description from the task’s desc: field. This makes the graph useful as a quick reference for what each task does, not just how they connect.
Mermaid graphs
If you prefer Mermaid over Graphviz — perhaps because your documentation is hosted on GitHub, which renders Mermaid natively — you can specify the graph type:
task-graph Taskfile.yml --output taskfile.md --graph-type mermaid
By default, Mermaid graphs flow top-down. You can change the direction to left-right, bottom-top, or right-left using the mermaid.direction setting in your configuration file.
Grouped tasks
As your Taskfile grows, grouping related tasks together can make the graph considerably easier to read. The --group-by-namespace flag wraps tasks that share a namespace into visual clusters:
task-graph Taskfile.yml --output taskfile.dot --group-by-namespace
Namespaces are detected from the task name. Formal namespaces use a colon as the delimiter — build:docker belongs to the build namespace. Where no colon is present, task-graph falls back to splitting on hyphens or dots, so lint-go would be grouped under lint and test.unit under test.
Nested namespaces are supported too. A task named build:docker:push would appear inside a docker cluster, itself inside a build cluster.
Coloured tasks
Colour is one of the most effective ways to make a complex graph scannable at a glance. task-graph supports two approaches.
Automatic colouring
The --auto-color flag assigns colours to tasks based on their namespace, cycling through a built-in palette of eight soft colours:
task-graph Taskfile.yml --output taskfile.dot --auto-color
Tasks in the same namespace get the same colour, making clusters of related work immediately visible. If you have more namespaces than palette entries, the colours wrap around. Any style rules you define in your configuration file take precedence over the auto-assigned colours, so you can use --auto-color as a baseline and override specific tasks as needed.
Custom style rules
For finer control, define nodeStyleRules in a configuration file. Each rule uses a glob pattern to match task names and applies the style properties you specify:
nodeStyleRules:
- match: "build*"
fillColor: lightyellow
- match: "tidy*"
fillColor: lightgreen
- match: "*test*"
fillColor: lightblue
- match: "lint"
fillColor: magenta
task-graph Taskfile.yml --output taskfile.dot --config config.yaml
Rules are applied in order, so if a task matches multiple patterns, the last match wins. You can set color (border), fillColor (background), style, and fontColor for each rule. See the Configuration page for the full set of options.
Highlighting tasks
When working with a large Taskfile, you might want to draw attention to specific tasks without styling the entire graph. The --highlight flag fills matching tasks with a highlight colour (yellow by default):
task-graph Taskfile.yml --output taskfile.dot --highlight "d*"
You can specify multiple patterns separated by commas or semicolons:
task-graph Taskfile.yml --output taskfile.dot --highlight "build*,test*"
The highlight colour can be changed by setting highlightColor in your configuration file — see the Configuration reference.
Exporting configuration
If you want to see the effective configuration after all defaults and CLI flags have been merged, export it to a file:
task-graph Taskfile.yml --output taskfile.dot --auto-color --export-config effective.yaml
This writes the merged configuration to effective.yaml (or .json, depending on the file extension). It is a useful way to understand exactly what settings are in play, and it serves as a solid starting point if you want to create your own configuration file from scratch rather than writing one by hand.