---
name: "gh-workflow-run"
section: "1"
platform: "linux"
package: "github-cli"
version: "2.102.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/gh-workflow-run"
---

# gh-workflow-run(1)

Run a workflow by creating a workflow\_dispatch event

## NAME

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

## SYNOPSIS

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

## 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

- **-F**, **--field** **\<key=value\>**

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

- **--json**

  Read workflow inputs as JSON via STDIN

- **-f**, **--raw-field** **\<key=value\>**

  Add a string parameter in key=value format

- **-r**, **--ref** **\<string\>**

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

## OPTIONS INHERITED FROM PARENT COMMANDS

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

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

## 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

```
# 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

**[gh-workflow(1)](/gh-workflow/1.md)**