Manage GitHub Sub-Issues and Dependencies via gh CLI

Structural Comparison Matrix

Check your gh version before any of this works

gh --version

Every flag in this post needs GitHub CLI v2.94.0 or later. If your version is older, update through whatever channel installed gh: brew upgrade gh on Homebrew, winget upgrade --id GitHub.cli --source winget on Windows, or your Linux package manager. This machine is running v2.97.0, and every command below was run against that install.

Set, change, or remove a parent issue

gh issue edit takes one number or URL argument for the parent, straight from GitHub’s own manual page:

gh issue edit 23 --parent 100

--parent does double duty. Run it once to link an unparented issue, or run it again later with a different number to move that issue under a new parent. There’s no separate flag for the two cases.

gh issue edit 23 --remove-parent

GitHub’s own 2026-06-10 announcement describes the same capability this way:

Link, change, or remove a parent with --parent, --set-parent, and --remove-parent.

Create a new issue directly as a sub-issue

gh issue create takes the same --parent flag, so a new issue can join the hierarchy at creation instead of needing a follow-up edit call:

gh issue create \
  --title "Fix login redirect loop after SSO callback" \
  --body "Users land back on /login after a successful SSO callback instead of the app." \
  --parent 100

The parent accepts a URL too, useful when the parent lives in a different repository: --parent https://github.com/cli/go-gh/issues/42, straight from the flag’s own documented example.

Link and unlink sub-issues from the parent side

The same relationship can be managed from the parent issue instead of the child, and --add-sub-issue takes a comma-separated list for more than one at a time:

gh issue edit 100 --add-sub-issue 123,124

gh issue edit 100 --remove-sub-issue 124

Read the hierarchy back with —json

gh issue view and gh issue list both expose parent, subIssues, and subIssuesSummary as JSON fields, so a script can read the tree without scraping HTML. Run against a real public issue on cli/cli itself, this is the actual shape gh returns:

gh issue view 5545 --repo cli/cli --json parent,subIssues,subIssuesSummary

{
  "parent": null,
  "subIssues": { "nodes": [], "totalCount": 0 },
  "subIssuesSummary": { "completed": 0, "percentCompleted": 0, "total": 0 }
}

That particular issue has no sub-issues linked, which is why the fields are empty. When they’re populated, subIssues.nodes holds the full list of child issue objects, and subIssuesSummary gives a ready-made completed/total/percentCompleted count, so a script doesn’t have to iterate the array itself to show progress.

Set and filter by issue type

gh issue edit 23 --type Bug

gh issue edit 23 --remove-type

gh issue list filters by the same field. This is real output from cli/cli’s own tracker, showing the full issueType object a populated field actually returns:

gh issue list --repo cli/cli --type Bug --limit 1 --json number,title,issueType

[
  {
    "issueType": {
      "id": "IT_kwDOA48Fh84AtH84",
      "name": "Bug",
      "description": "An unexpected problem or behavior",
      "color": "RED"
    },
    "number": 9569,
    "title": "Can't install / update `gh` due to expired GPG key?"
  }
]

Set cross-issue dependencies

Dependencies are separate from parent/child hierarchy. “Blocked by” and “blocking” describe ordering between two issues that don’t need a parent-child relationship at all:

gh issue edit 123 --add-blocked-by 200 --add-blocking 300,301

Both flags take comma-separated lists, and both directions can be set in the same call, as shown in gh issue edit’s own --help output. Remove either side the same way:

gh issue edit 123 --remove-blocked-by 200

gh issue create has the equivalent flags for setting dependencies at creation time: --blocked-by and --blocking, both accepting the same comma-separated issue-number or URL lists.

Where this fits in the wider gh CLI wave

Sub-issue and dependency support shipped in the same v2.94.0 release as gh discussion, GitHub CLI’s new command group for GitHub Discussions. Neither depends on the other; they landed the same day because both closed a gap where GitHub.com had a feature gh couldn’t touch at all. See gh discussion: GitHub Discussions in Your Terminal for that side of the same release, and GitHub CLI’s 2026 Agent-Era Expansion for the full ten-part wave this cluster belongs to.

Reach for these flags the moment you’re managing more than a handful of issues in one hierarchy, triaging a big feature into sub-issues from a script, or wiring an agent to file work broken down by parent task automatically. For a one-off parent link on a single issue, the GitHub.com sidebar is still fewer keystrokes. Once you’re doing it more than once, gh issue edit --parent is the version that survives being scripted.

Browse more coverage like this in the Dev Tools archive.