gh-run

Interactively select a run to see information about the jobs

$ gh run view

$ gh run view [workflow_run_number]

$ gh run view [[-j|--job]] [job_number]

$ gh run view [[-j|--job]] [job_number] --log

$ gh run view [workflow_run_number] --exit-status && [echo "run pending or passed"]

$ gh run watch

$ gh run watch [workflow_run_number]

$ gh run rerun [workflow_run_number]

gh run <list|view|download|watch|cancel|approve|rerun> [<run-id>] [options]

--branch <branch>
    Filter by branch name or ref

--limit <number>
    Maximum number of runs to list (default 20)

--repo <OWNER/REPO>
    Repository to interact with

--status <status>
    Filter by status: queued, in_progress, success, failure

--workflow <query>
    Filter by workflow ID, filename, or name

--name <artifact-name>
    Download specific artifact (for download)

--jq <expression>
    Query JSON output using JMESPath

--json <fields>
    Output JSON fields only

The gh run command is part of the GitHub CLI (gh) for interacting with GitHub Actions workflow runs from the terminal. It enables listing recent runs, viewing details, downloading artifacts, watching progress, canceling jobs, approving workflows, and rerunning failures.

Use it to debug CI/CD pipelines, automate monitoring, or integrate Actions into scripts. Filter by branch, status (queued, in_progress, success, failure), or workflow ID/file. Specify repo with --repo if outside a Git repo.

Key subcommands: list shows runs with optional limits/filters; view displays logs/jobs; download fetches artifacts; watch tails live output; cancel/rerun controls execution. Outputs JSON via --jq for scripting. Requires gh auth login for access.

Requires GitHub CLI authentication via gh auth login. Limited to repos with read access. Interactive prompts (watch, view) fail in non-TTY. Enterprise Server support varies by version.

gh run list --branch main --status failure
gh run view 123456
gh run download 123456 --name my-artifact
gh run watch 123456

list: List runs.
view <id>: Show details/logs.
download <id>: Fetch artifacts.
watch <id>: Tail progress.
cancel <id>: Stop run.
rerun <id>: Retry failures.

Introduced in GitHub CLI v0.5.0 (Feb 2020) with basic list/view. Expanded in v1.x+ (2021+) to include download, watch, cancel, rerun, and artifact/job management. Tracks GitHub Actions API evolution.

gh(1), gh-workflow(1), git(1)