GH-WORKFLOW-RUN(1)

💅 GH-WORKFLOW-RUN — the GitHub CLI manual, bestie edition ✨

okay so you want to run a workflow. from your terminal. like a main character. this is that page. it's from the GitHub CLI manual and it's literally about firing off a workflow_dispatch event, and yes you're gonna slay it 🎀

---

🌸 NAME

gh-workflow-run — Run a workflow by creating a workflow_dispatch event

no cap, that's the whole vibe. you point at a workflow, gh pokes GitHub Actions, the thing runs. iconic.

---

✨ SYNOPSIS

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

you can pass a workflow-id or a workflow-name (or honestly nothing at all and let gh ask you, we love a prompt 💖), plus whatever flags you're feeling.

---

🦋 DESCRIPTION

So the whole point: this creates a workflow_dispatch event for a given workflow. that means it triggers GitHub Actions to run a given workflow file. fr fr. 🔥

⚠️ important caveat bestie: the workflow file must support an on.workflow_dispatch trigger in order to be run this way. if it doesn't, this command is not it. it will not happen. periodt.

If the workflow file supports inputs, you've got a few ways to give them to it:

• Interactively 💬 (gh just asks you, cozy)
• Via the -f/--raw-field or -F/--field flags 🏁
• As JSON, via standard input 🧚

And the created workflow run URL will be returned if available. cute little treat at the end 🍓

---

👑 OPTIONS

• -F, --field <key=value> — add a string parameter in key=value format, respecting @ syntax (see gh help api). the @ thing is a whole vibe, go read that other page iykyk
• --json — read workflow inputs as JSON via STDIN. pipe it in, live your truth 🫶
• -f, --raw-field <key=value> — add a string parameter in key=value format. the simple one. no @ syntax nonsense here, just vibes
• -r, --ref <string> — branch or tag name which contains the version of the workflow file you'd like to run. so you can run the workflow file from some other branch, not just the default one. slay 🌈

---

💜 OPTIONS INHERITED FROM PARENT COMMANDS

• -R, --repo <[HOST/]OWNER/REPO> — select another repository using the [HOST/]OWNER/REPO format. yes the brackets are real. yes HOST/ is optional. no we're not skipping it 💀

---

⭐ EXIT CODES

• 0 — Successful execution 🎉 ate, no crumbs
• 1 — Error 😭
• 2 — Command canceled 🙈
• 4 — Authentication required 🔐 (go log in bestie)

NOTE: Specific commands may have additional exit codes. Refer to the command's help for more information. so like, check the specific command's help if something weird happens. don't come for me 💅

---

🎀 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

not the Scully and "hello" reference, we love a callback 💖

---

🌺 SEE ALSO

• gh-workflow(1) — the parent command, go say hi

---

aaaand that's the whole page, bestie 🌈 this was GitHub CLI v2.102.0, dated Oct 2026, and it's the GH-WORKFLOW-RUN(1) manual page — go run a workflow, you've got this 👑💅✨