GH-WORKFLOW-RUN(1) GitHub CLI manual GH-WORKFLOW-RUN(1)

# [NAME](#NAME)

gh-workflow-run - Run a workflow by creating a workflow\_dispatch event

# [SYNOPSIS](#SYNOPSIS)

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

# [DESCRIPTION](#DESCRIPTION)

Create a **workflow\_dispatch** event for a given workflow.

This command will trigger GitHub Actions to run a given workflow file. The given workflow file must support an **on.workflow\_dispatch** trigger in order to be run in this way.

If the workflow file supports inputs, they can be specified in a few ways:

- Interactively
- Via **-f/--raw-field** or **-F/--field** flags
- As JSON, via standard input

The created workflow run URL will be returned if available.

# [OPTIONS](#OPTIONS)

[**-F**, **--field** **<key=value>**](#F)

Add a string parameter in key=value format, respecting @ syntax (see "gh help api").

[**--json**](#json)

Read workflow inputs as JSON via STDIN

[**-f**, **--raw-field** **<key=value>**](#f)

Add a string parameter in key=value format

[**-r**, **--ref** **<string>**](#r)

Branch or tag name which contains the version of the workflow file you'd like to run

# [OPTIONS INHERITED FROM PARENT COMMANDS](#OPTIONS_INHERITED_FROM_PARENT_COMMANDS)

[**-R**, **--repo** **<\[HOST/\]OWNER/REPO>**](#R)

Select another repository using the \[HOST/]OWNER/REPO format

# [EXIT CODES](#EXIT_CODES)

0: Successful execution

1: Error

2: Command canceled

4: Authentication required

NOTE: Specific commands may have additional exit codes. Refer to the command's help for more information.

# [EXAMPLE](#EXAMPLE)

```
# Have gh prompt you for what workflow you'd like to run and interactively collect inputs
$ gh workflow run
# Run the workflow file 'triage.yml' at the remote's default branch
$ gh workflow run triage.yml
# Run the workflow file 'triage.yml' at a specified ref
$ gh workflow run triage.yml --ref my-branch
# Run the workflow file 'triage.yml' with command line inputs
$ gh workflow run triage.yml -f name=scully -f greeting=hello
# Run the workflow file 'triage.yml' with JSON via standard input
$ echo '{"name":"scully", "greeting":"hello"}' | gh workflow run triage.yml --json
```

# [SEE ALSO](#SEE_ALSO)

[**gh-workflow(1)**](/man/os/gh/gh-workflow.1)

Oct 2026

---

Document: gh-workflow-run(1) from gh 2.103.3-r1 (Chainguard OS)
Source: https://github.com/cli/cli