ghcli / Automation & API / gh workflow run

gh workflow run

Kick off an Actions workflow on demand

gh workflow run triggers a workflow that has a workflow_dispatch trigger, straight from your terminal. Pass inputs, choose the branch or tag to run on, and start deployments or one-off jobs without opening the Actions tab.

Quick answer

gh workflow run deploy.yml

↧ Download snippet Full cheat sheet

Syntax

gh workflow run [<workflow-id> | <workflow-name> | <filename>] [flags]

Examples

Run a workflow by filename

gh workflow run deploy.yml

Run on a specific branch

gh workflow run deploy.yml --ref release-2.0

Pass inputs to the workflow

gh workflow run deploy.yml -f environment=prod -f version=1.4.0

Provide inputs as JSON on stdin

echo '{"environment":"prod"}' | gh workflow run deploy.yml --json

Pick interactively from a list

gh workflow run

Options & flags

Flag	What it does
-r, --ref	The branch or tag to run the workflow on.
-f, --raw-field	Set a string input (key=value).
-F, --field	Set a typed input (numbers, booleans, @file).
--json	Read workflow inputs as JSON from standard input.

How to use gh workflow run, step by step

Make sure the workflow has an on: workflow_dispatch trigger.
List available workflows with gh workflow list.
Run gh workflow run deploy.yml -f environment=prod.
Watch it with gh run watch once it starts.

Common errors and fixes

Workflow does not have 'workflow_dispatch' trigger

Only workflows with on: workflow_dispatch can be started this way. Add that trigger to the workflow YAML.

could not find any workflows named deploy.yml

Check the exact filename or name with gh workflow list; the file lives under .github/workflows/.

Required input 'environment' not provided

The workflow declares required inputs. Supply them with -f environment=prod.

Related commands

Frequently asked questions

How do I trigger a GitHub Actions workflow from the command line?

Run gh workflow run <file>, e.g. gh workflow run deploy.yml. The workflow must have an on: workflow_dispatch trigger. Pass inputs with -f key=value.

How do I pass inputs to a manually triggered workflow?

Use -f for string inputs and -F for typed ones: gh workflow run deploy.yml -f environment=prod -f version=1.4.0.

How do I run a workflow on a specific branch?

Add --ref with the branch or tag name: gh workflow run deploy.yml --ref release-2.0.