Usage: task-graph --output=STRING <taskfile> [flags]
Arguments:
<taskfile> Path to the taskfile to process.
Flags:
-h, --help Show context-sensitive help.
-o, --output=STRING Path to the output file.
-c, --config=STRING Path to a config file (YAML or JSON).
--group-by-namespace Group tasks in the same namespace together in
the output.
--auto-color Automatically color nodes by namespace using a
built-in palette.
--graph-type=STRING Type of graph to generate (dot or mermaid).
Defaults to dot.
--highlight=STRING Highlight specific tasks in the graph. Accepts
task names or glob patterns, separated by
commas or semicolons.
--render-image=STRING Render the graph as an image using graphviz
dot. Specify the file type (e.g. png, svg).
--export-config=STRING Export the effective configuration to a file
(YAML or JSON based on file extension).
--verbose Enable verbose logging.
Arguments
<taskfile>
The path to the Taskfile to process. This is required and must point to a valid Taskfile (typically Taskfile.yml or Taskfile.yaml).
Flags
--output, -o
Required. The path for the generated output file. For Graphviz output, this is conventionally a .dot file. For Mermaid output, .md works well. When combined with --render-image, the image file takes its name from this path with the extension replaced.
--config, -c
Path to a configuration file in YAML or JSON format. See the Configuration page for the full set of available settings. Command-line flags override values from the configuration file.
--graph-type
Selects the output format. Accepted values are dot (the default) for Graphviz and mermaid for Mermaid flowcharts.
task-graph Taskfile.yml --output taskfile.md --graph-type mermaid
--group-by-namespace
Groups tasks that share a namespace into visual clusters. In Graphviz output, this produces subgraph clusters with labelled borders. In Mermaid output, it produces nested subgraph blocks.
Namespaces are detected from task names — a colon delimiter (e.g., build:docker) indicates a formal namespace, while hyphens and dots (e.g., lint-go, test.unit) are used as fallback delimiters.
task-graph Taskfile.yml --output taskfile.dot --group-by-namespace
--auto-color
Automatically assigns colours to task nodes based on their namespace, cycling through a built-in palette. This is a quick way to make namespaces visually distinct without writing a configuration file. Any node style rules defined in a configuration file take precedence over the auto-assigned colours.
task-graph Taskfile.yml --output taskfile.dot --auto-color
--highlight
Fills matching tasks with a highlight colour (yellow by default) to draw attention to them. Accepts task names or glob patterns. Multiple patterns can be separated by commas or semicolons.
task-graph Taskfile.yml --output taskfile.dot --highlight "build*,test*"
The highlight colour can be changed with the highlightColor setting in your configuration file.
--render-image
Renders the graph directly to an image by invoking the Graphviz dot executable. Specify the desired file type — e.g., png, svg, or pdf. The output image file takes its name from the --output path with the extension replaced.
task-graph Taskfile.yml --output taskfile.dot --render-image png
This requires dot to be available on your system PATH, or you can specify its location via the dotPath setting in your configuration file. This flag only applies to Graphviz output.
--export-config
Writes the effective configuration — after merging defaults, config file values, and command-line flags — to the specified file. The format is determined by the file extension: .yaml or .yml for YAML, .json for JSON.
task-graph Taskfile.yml --output taskfile.dot --auto-color --export-config effective.yaml
This is useful for debugging which settings are actually in play, or as a starting point for creating your own configuration file.
--verbose
Enables detailed logging output, which can be helpful when diagnosing unexpected behaviour.