---
name: "gt-workflow-run"
section: "1"
platform: "linux"
package: "gitea-cli"
version: "1.0.0-1"
release: "Arch Linux 2026-11-07"
platforms: ["linux"]
url: "https://carta.tech/man/gt-workflow-run"
---

# gt-workflow-run(1)

Dispatch a workflow

## NAME

gt-workflow-run - Dispatch a workflow

## SYNOPSIS

**gt workflow run \<workflow\> \[flags\]**

## DESCRIPTION

Start a run of a workflow that has a workflow\_dispatch trigger.

Inputs are checked against the inputs that the workflow declares: unknown inputs, missing required inputs and values that a choice, boolean or number input does not accept are refused. In a terminal, gt asks for missing required inputs, or for every input when none is given.

The workflow is looked up, like Gitea does, among the files in the first of .gitea/workflows and .github/workflows that exists on the branch or tag it runs on, so one that exists only on a branch runs with --ref. gt workflow list shows those of the default branch.

Without --ref, the workflow runs on the checked-out branch, which must be on the server, or on the default branch when the repository does not come from the working directory.

With --follow, the command exits with 5, like gt run watch, when the run completes without success, and with 3 when --timeout expires first.

### ARGUMENTS

```
A workflow can be supplied as its file name ("ci.yml"), its file name without
extension ("ci"), its path (".gitea/workflows/ci.yml") or its name ("CI").
```

### JSON FIELDS

```
id, url
```

## OPTIONS

**-f**, **--field**=\[\]\
 	Workflow input as **key=value** (repeatable)

**--follow**\[=false\]\
 	Follow the logs of the run's jobs after dispatching it

**-h**, **--help**\[=false\]\
 	help for run

**-i**, **--interval**=2s\
 	Polling interval with --follow

**-r**, **--ref**=""\
 	Branch or tag to run the workflow on (default: the current or default branch)

**--timeout**=30m0s\
 	Maximum time to follow

## OPTIONS INHERITED FROM PARENT COMMANDS

**--csv**\[=""\]\
 	Output CSV with the specified comma-separated **fields**, or all fields

**--cwd**=""\
 	Working **directory** for repository discovery

**--debug**\[=false\]\
 	Log the method, URL, status, and duration of each HTTP request to stderr

**--host**=""\
 	Gitea instance **URL**, including any base path

**--interactive**\[=false\]\
 	Allow prompts with machine output

**-q**, **--jq**=""\
 	Filter JSON output using a jq **expression**; implies --json

**--json**\[=""\]\
 	Output JSON with the specified comma-separated **fields**, or all fields

**--no-input**\[=false\]\
 	Disable prompts and implicit editor/browser interactions

**--remote**=""\
 	Git **remote** used for repository discovery

**-R**, **--repo**=""\
 	Select a repository as **OWNER/REPO** or URL

**--sudo**=""\
 	Perform API requests as this **user** (requires an administrator account)

**--user**=""\
 	Account **name** on the selected instance

## EXAMPLE

```
# run a workflow on the default or current branch
$ gt workflow run CI
# run it on a branch with inputs
$ gt workflow run ci.yml --ref main -f target=production -f dry_run=false
# run it and follow the logs of its jobs
$ gt workflow run nightly --follow
```

## SEE ALSO

**[gt-workflow(1)](/man/gt-workflow/1.md)**