gh workflow list: Usage, Options & Common CI Errors
List the Actions workflows in a repository, with their states and IDs.
gh workflow list shows the workflows defined in a repository - their names, states (active/disabled), and IDs - which you need to dispatch, enable, or disable them.
What it does
gh workflow list enumerates the repository’s workflows. The output gives each workflow’s name, state, and numeric ID; --all includes disabled workflows. The ID or file name is what you pass to gh workflow run, enable, or disable.
Common usage
# List active workflows
gh workflow list
# Include disabled workflows
gh workflow list --all
# JSON output for scripting
gh workflow list --json name,id,state --jq '.[] | [.name, .id] | @tsv'Common error in CI: no workflows / wrong repo context
gh workflow list returns nothing when the repo has no workflows on the default branch, or errors with no repo context outside a clone. Fix: ensure .github/workflows/*.yml exists on the repo’s default branch (the Actions API only sees workflows there), and pass --repo owner/name in CI jobs that run outside a checkout. Use --all to surface disabled workflows you intend to enable. Token needs actions: read.
Key options
| Option | Purpose |
|---|---|
| -a, --all | Include disabled workflows |
| --json FIELDS | Output JSON with chosen fields |
| -L, --limit | Maximum number to list |
Using this in CI
Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.
- Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange
id-token: writefor cloud credentials with no stored secret. - Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
- Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
- Set the output format explicitly (
--output json) rather than relying on the default, which can differ by version and configuration profile.