Listing Available Workflows in act: Command Line Guide

Use act --list (or -l) to enumerate every GitHub Actions workflow file discovered in your repository without executing any jobs.

The nektos/act CLI tool enables local execution of GitHub Actions, and listing available workflows is the first step to verifying your CI/CD configuration. Before running any jobs, you can generate a complete inventory of workflow names, job IDs, triggering events, and file locations directly from the terminal.

How the --list Flag Works

When you invoke the list command, the root command in [cmd/root.go](https://github.com/nektos/act/blob/master/cmd/root.go#L71) initializes a workflow planner via model.NewWorkflowPlanner. This planner constructs a workflow plan by scanning the designated workflows directory and parsing each YAML file.

The root command then passes this plan to the printList function defined in [cmd/list.go](https://github.com/nektos/act/blob/master/cmd/list.go). This function iterates through plan.Stages and their associated stage.Runs to extract:

• Job ID and job name (via Run.String())
• Stage number representing execution order
• Workflow name and source file path
• Triggering events (via Workflow.On())

The formatter calculates column widths dynamically and prints an aligned table to stdout. If the plan contains no jobs, the command succeeds with an empty table rather than an error.

Command Line Usage

List workflows in the default .github/workflows/ directory:

act --list

Or use the short flag:

act -l

Specify a custom workflows directory with the --workflows option:

act --workflows ./my-custom-workflows --list

Workflow Discovery and Parsing

The discovery process begins with the WorkflowsPath method in [cmd/input.go](https://github.com/nektos/act/blob/master/cmd/input.go#L103), which defaults to ./.github/workflows/ unless overridden by the --workflows flag.

The planner (implemented in pkg/model/planner.go) walks this directory and invokes ReadWorkflow from [pkg/model/workflow.go](https://github.com/nektos/act/blob/master/pkg/model/workflow.go) to parse each *.yml or *.yaml file. During parsing, the tool extracts workflow metadata including event triggers (On()), job definitions, and dependencies to build the execution plan.

Understanding the Output Format

The standard output displays six columns in a fixed-width table:

Stage  Job ID  Job name       Workflow name   Workflow file   Events
0      build   Build          CI              ci.yml          push,pull_request
0      test    Test           CI              ci.yml          push,pull_request
1      deploy  Deploy         Release         release.yml     release

• Stage: Numeric execution group (jobs in stage 0 run before stage 1)
• Job ID: The unique identifier used to reference the job
• Job name: Human-readable name displayed in logs
• Workflow name: The name: field from the YAML file
• Workflow file: Relative path to the source file
• Events: Comma-separated list of GitHub events that trigger this workflow

Duplicate Job ID Detection

If multiple workflows contain identical job IDs, act appends a warning after the table:

Detected multiple jobs with the same job name, use `-W` to specify the path to the specific workflow.

This reminder indicates that you must use the -W flag to target a specific workflow file when running jobs with colliding identifiers.

Summary

• Use act --list to enumerate all workflows without executing them.
• Default search path is ./.github/workflows/ as implemented in cmd/input.go.
• The planner (pkg/model/planner.go) validates and loads YAML files into a structured plan.
• Output includes stage numbers, job IDs, workflow names, file paths, and triggering events.
• Duplicate detection warns when job IDs collide across multiple workflow files.

Frequently Asked Questions

What information does act --list display exactly?

The command displays a table containing the stage number, job ID, job name, workflow name, source file path, and triggering events for every job discovered in the workflows directory. This corresponds to the data extracted by printList in cmd/list.go from the workflow plan's stages and runs.

Can I list workflows stored in a non-standard directory?

Yes. Use the --workflows flag to specify an alternative path. The WorkflowsPath() method in cmd/input.go handles this override, allowing you to point to any directory containing valid workflow YAML files.

Why do I see a warning about duplicate job names?

When two or more workflows contain jobs with identical IDs, act cannot determine which to execute by name alone. The printList function detects these collisions and prints a hint to use -W to specify the exact workflow file path when running specific jobs.

Does act --list validate workflow syntax?

Yes, indirectly. The workflow planner in pkg/model/planner.go parses each file using ReadWorkflow from pkg/model/workflow.go. If a YAML file contains syntax errors or invalid workflow structures, the parsing will fail and act will report the error before displaying any list.

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