gh workflow: List and Inspect Actions Workflows
gh workflow lists the Actions workflows in a repo, shows a workflow's recent runs, and can enable, disable, or dispatch a workflow from the terminal.
The GitHub CLI does not validate workflow YAML (use actionlint for that), but gh workflow is how you inspect and trigger workflows in scripts and confirm a new workflow registered after a push.
What it does
gh workflow operates on the Actions API: list shows workflows and their state, view shows a workflow and its recent runs, run dispatches a workflow_dispatch event, and enable/disable toggle a workflow. It works against the current repo or -R owner/repo.
Common usage
gh workflow list
gh workflow view ci.yml
gh workflow run deploy.yml --ref main -f env=staging
gh workflow disable nightly.ymlOptions
| Command / flag | What it does |
|---|---|
| gh workflow list | List workflows and their enabled state |
| gh workflow view <file|id> | Show a workflow and recent runs |
| gh workflow run <file> | Dispatch a workflow_dispatch event |
| --ref <branch> | Ref to run the dispatched workflow on |
| -f, --field <key=val> | Provide workflow_dispatch inputs |
| -R, --repo <owner/repo> | Target a specific repo |
In CI
Use gh workflow in scripts to trigger dependent workflows or verify a workflow exists after adding it. It needs a token with actions scope (GH_TOKEN). It does not lint YAML, so keep actionlint as the config gate.
Common errors in CI
could not find any workflows named ... means the file name or id is wrong. Workflow does not have workflow_dispatch trigger means you cannot gh workflow run it. HTTP 401: Bad credentials or gh: To use GitHub CLI ... set the GH_TOKEN means no auth token. gh: command not found means the CLI is not installed.