Jira Issue Hierarchy and Epics, Explained (with CLI queries)

atlassian-cli is an independent, community open-source project, not affiliated with, endorsed by, or sponsored by Atlassian, and is not Atlassian's official CLI (acli). Product names are used only to identify compatibility.

What is the Jira hierarchy?

The Jira hierarchy is the parent-and-child structure that organizes work into tiers. In a default Jira Cloud project there are three levels: epics at the top, standard issues (stories, tasks, and bugs) in the middle, and subtasks at the bottom. Every item reports up to exactly one parent on the level directly above it, so the whole project forms a set of trees rooted at epics.

That model is easy to click through in the Jira web UI one issue at a time, but it is slow to audit at scale. If you want to answer questions like "which epics still have open children?" or "how many subtasks are left on this story?", the command line is far faster. This guide explains each level in plain terms, then shows the exact atlassian-cli commands that query and walk the hierarchy using JQL.

How this differs from Atlassian's acli: atlassian-cli is an independent, community, MIT-licensed open-source project. It is not Atlassian's official CLI (acli) and is not affiliated with, endorsed by, or sponsored by Atlassian. Use the official acli if you need first-party vendor support. Use atlassian-cli if you want a single free Rust binary that spans Jira, Confluence, Bitbucket, and Jira Service Management, and that pipes cleanly into shell tools like jq.

The four levels, top to bottom

Jira assigns each hierarchy level an integer. Standard issues are level 0, subtasks are level -1 (below standard), and epics are level 1 (above standard). On Premium plans, Atlassian's advanced planning features let you add custom levels above epics, most commonly an Initiative level that groups several epics under one strategic theme. Here is the full picture:

Two facts about this table matter in practice. First, the standard tier holds more than just stories: tasks and bugs live there too, side by side, all at level 0. Second, the Initiative row only exists if your instance is on a plan that supports extra levels and an admin has configured them. On a standard free or Standard-plan project, the hierarchy stops at epic.

Query each level from the CLI

Every query below is a plain jira issue search with a JQL string. The JQL functions standardIssueTypes() and subTaskIssueTypes() resolve to whatever types your instance maps to those tiers, so they keep working even when a project renames its issue types.

# All epics in a project
atlassian-cli jira issue search \
  --jql "project = DEV AND issuetype = Epic" \
  --limit 100

# All standard issues (stories, tasks, bugs) - no epics, no subtasks
atlassian-cli jira issue search \
  --jql "project = DEV AND issuetype in standardIssueTypes()"

# Every subtask in the project
atlassian-cli jira issue search \
  --jql "project = DEV AND issuetype in subTaskIssueTypes()"

Add --format json to any of these to get machine-readable output, or --format csv --output level.csv to open the result in a spreadsheet. For a broader JQL reference, including date functions and status filters you can combine with the type filters above, see the JQL query cheat sheet.

Traverse an epic to its children

Knowing the level of an issue is only half the job. The more useful question is "what sits under this specific epic?" The answer is the parent JQL field, which points one level up from any child. To list the direct children of epic DEV-100:

# Direct children of an epic (stories, tasks, bugs)
atlassian-cli jira issue search \
  --jql "parent = DEV-100" \
  --limit 100

The same parent field works one tier lower. To list the subtasks of story DEV-123, point parent at the story:

# Subtasks of a single story
atlassian-cli jira issue search \
  --jql "parent = DEV-123 AND issuetype in subTaskIssueTypes()"

One compatibility note. Newer Jira Cloud projects use the unified parent field for both epic-to-story and story-to-subtask links. Some older company-managed projects still store the epic relationship in the classic Epic Link field. If parent = DEV-100 returns nothing on such a project, query the field by name instead (mind the quoting so the shell keeps the inner double quotes):

# Classic company-managed projects: query the Epic Link field
atlassian-cli jira issue search \
  --jql '"Epic Link" = DEV-100'

To inspect a single issue and see its own parent, status, and type in one shot, use jira issue get:

atlassian-cli jira issue get DEV-123 --format json | jq '{key, type: .fields.issuetype.name, parent: .fields.parent.key, status: .fields.status.name}'

Build a hierarchy tree with jq

atlassian-cli does not ship a dedicated tree command, but the two queries above compose into one. List every epic in a project, then loop over each epic key and query its children. Because --format json returns a plain array, jq can pull out exactly the fields you want:

#!/bin/bash
# Print a project's epic -> child tree
set -euo pipefail
PROJECT="DEV"

atlassian-cli jira issue search \
  --jql "project = $PROJECT AND issuetype = Epic" \
  --format json | jq -r '.[].key' | while read -r EPIC; do
    echo "Epic: $EPIC"
    atlassian-cli jira issue search \
      --jql "parent = $EPIC" \
      --format json | jq -r '.[] | "  - \(.key) [\(.fields.status.name)] \(.fields.summary)"'
done

That prints each epic followed by an indented list of its children with status and summary. It is a quick way to review an entire release without leaving the terminal. You can also roll the children up by status to see how much of an epic is still open:

# Count an epic's children by status
atlassian-cli jira issue search \
  --jql "parent = DEV-100" \
  --format json | jq 'group_by(.fields.status.name)
    | map({status: .[0].fields.status.name, count: length})'

If you run reviews like this every sprint, wire the loop into a scheduled report. The task management from the CLI guide covers turning ad-hoc queries into repeatable workflows, and the Jira CLI reference lists every issue and search flag in one place.

Create issues at each level

Creating hierarchy is the mirror image of querying it. You create the parent first, then attach children. An epic is just an issue with the Epic type:

# Create an epic
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Epic \
  --summary "Checkout redesign"

Linking a child to that epic means setting the parent (or classic Epic Link) field at create time. The exact field ID varies by instance, so discover it first with jira fields list, then pass it through the generic --field flag, which accepts a raw fieldId=value pair:

# 1. Find the field that stores the epic/parent link
atlassian-cli jira fields list --format json \
  | jq '.[] | select(.name | test("Epic|Parent"; "i")) | {id, name}'

# 2. Create a story under epic DEV-100 using the field id you found
#    (customfield id shown here is an example - use yours)
atlassian-cli jira issue create \
  --project DEV \
  --issue-type Story \
  --summary "Cart summary widget" \
  --field 'customfield_10014="DEV-100"'

The --field mechanism is the same one you use for any custom field, so once you know the ID, epic links, sprints, and other custom values all set the same way. If you would rather group existing issues after the fact, the parent relationship can also be changed with jira issue update and the same field flag, and you can move issues in bulk with the patterns in the complete Jira CLI guide.

Common hierarchy gotchas

A few details trip people up when they first script against the hierarchy. Knowing them up front saves a lot of confusion when a query returns fewer rows than expected.

• An epic query returns only one level. parent = DEV-100 lists the epic's direct children (the stories, tasks, and bugs), not their subtasks. A subtask's parent is its own story, not the epic, so reaching the bottom of the tree takes two hops: query the epic for its children, then query each child for its subtasks.
• standardIssueTypes() deliberately excludes epics and subtasks. It resolves to the level-0 types only. If you want everything in a project regardless of tier, drop the type filter and query project = DEV on its own.
• Watch the page size. A large epic can have more children than a single page returns. Raise --limit when you traverse busy epics so the loop does not silently miss issues, for example --limit 200.
• Parent versus Epic Link. Team-managed and newer company-managed projects use the unified parent field; some legacy company-managed projects still use the classic Epic Link. If one returns nothing, try the other before assuming the epic is empty.
• Issue-type names are per project. A project may rename "Story" or add a custom subtask type. That is exactly why the function filters standardIssueTypes() and subTaskIssueTypes() are safer than hard-coding issuetype = Story in reusable scripts.

Keep these in mind and the traversal script from earlier stays correct across every project shape, from a tidy free-plan board to a Premium instance with an initiative tier on top.

FAQ

Related Resources