---
title: Jira
description: Map Jira issue links, parents, subtasks, and remote links through the Atlassian Teamwork Graph CLI (twg), then open the run in the dashboard.
url: "https://issue-graph.dev/docs/jira"
docs_index: /llms.txt
canonical_url: "https://issue-graph.dev/docs/jira"
---

# Jira

> For an index of all documentation, see [/llms.txt](/llms.txt).

`issue-graph jira` starts from one Jira issue and maps what it blocks, what blocks it, its duplicates and related work, its parent and subtasks, and its remote links. It reads Jira through the [Atlassian Teamwork Graph CLI](https://github.com/atlassian/twg-cli) (`twg`), so your Atlassian session stays in `twg`, and it saves the run to the same dashboard as GitHub and Linear.

## Connect Jira

`issue-graph jira` needs `twg` 1.4 or later on your `PATH`. Install it from the [twg repository](https://github.com/atlassian/twg-cli), then sign in once:

```bash
twg login
```

issue-graph doesn't install `twg`, start its login, or read its credentials. When `twg` isn't on your `PATH`, the command fails with `TWG_NOT_FOUND`.

## Map an issue neighborhood

Pass an issue key with `--site`, or a browse URL, which names the site for you:

```bash
issue-graph jira ABC-123 --site your-site --open
```

```bash
issue-graph jira https://your-site.atlassian.net/browse/ABC-123 --json
```

The report prints as Markdown by default, and `--json` prints the versioned JSON report instead. `--open` writes an HTML explorer, opens it in your browser, and saves the run to the dashboard. `--html PATH` writes the explorer to a path you choose and also saves the run.

## Open Jira runs in the dashboard

Jira runs open in the same explorer as GitHub and Linear, with the Jira mark, native status names, and the Explore and Swarm views. issue-graph saves one model per site and seed project, with an ID such as `jira:your-site.atlassian.net:project:ABC`. A new run from the same project replaces the saved model.

- `issue-graph dashboard` lists the Jira project next to your other saved runs in the project switcher.
- `issue-graph query jira:your-site.atlassian.net:project:ABC` filters the saved run without calling `twg`.
- `--no-save` writes the explorer without saving the run.
- `--cluster` prints a thematic clustering task for the calling agent, and `--clusters PATH` applies its proposed themes to `--html` or `--open`.

The command writes local files only with `--html` or `--open`. Status categories map to dashboard states, so `done` is closed and `new` or `indeterminate` is open.

## Choose the site

`--site` accepts a site prefix, a domain, or a cloud ID, the same values `twg --site` accepts. Without `--site` or a browse URL, `twg` uses its default site.

| `--site` value | Example                                | How issue-graph checks it                                    |
| -------------- | -------------------------------------- | ------------------------------------------------------------ |
| Domain         | `your-site.atlassian.net`              | Must equal the site of every issue `twg` returns             |
| Prefix         | `your-site`                            | Must be the first label of every issue's site                |
| Cloud ID       | `00000000-0000-4000-8000-000000000001` | With a browse URL, the first issue's site must match the URL |

A browse URL and a `--site` value that name different sites fail before any read. Node keys have the form `jira:<site>:<KEY>`, with the site taken from the web URL `twg` returns for the first issue, so keys from different sites can't collide.

## What the graph includes

- Issue links in both directions with their native type, such as `Blocks`, `Duplicate`, `Relates`, or `Cloners`. `Relates` is undirected.
- Parent and subtask relationships.
- HTTP and HTTPS remote links with their titles, such as linked pull requests.
- Native status, status category, issue type, and update time.

Links between issues in the seed's project recurse up to `--depth`. A link into another project is read at the next depth and isn't expanded, so the `--max-nodes` cap reaches direct neighbors in other projects before deeper work in the seed's project.

issue-graph lists remote link targets without fetching them. It doesn't collect issue keys mentioned in summaries, descriptions, or comments, so text such as `UTF-8` never turns into a read.

### Why epic children aren't listed

Jira's `subtasks` field lists only sub-task children, so the command doesn't read the children of an epic or of another issue above the sub-task level. An issue like this is partial when the command expands it, and a depth boundary when the command doesn't. An issue whose type has no `hierarchyLevel`, or whose `subtasks` field is missing or null, is treated the same way unless its type is a sub-task. Start from a child issue to see its parent.

## How issue-graph reads Jira

issue-graph runs one `twg` process per issue, without a shell:

```bash
twg jira workitem get ABC-123 --fields summary,status,issuetype,project,parent,subtasks,issuelinks,updated --remote-links --output json --output-summary=none --site your-site
```

`--output-summary=none` keeps raw JSON on stdout even when `twg` runs with agent output defaults. `--concurrency` sets how many `twg` processes run at once, from 1 to 16, with a default of 4.

## Coverage and exit codes

The command exits with `0` when coverage is complete within the requested scope, `1` when coverage is partial or the first issue can't be read, and `2` for invalid arguments.

These conditions make coverage partial:

- A linked issue that can't be read. It stays in the graph as unavailable with an error code, such as the code `twg` reports, `IDENTITY_MISMATCH` when the issue moved to another key, or `SITE_MISMATCH` when it belongs to another site.
- A `twg` warning, such as a failed remote-link read, or a `twg` response that reports partial coverage or truncation.
- An expanded issue whose children aren't listed, as described in [Why epic children aren't listed](#why-epic-children-arent-listed).
- The `--max-nodes` cap or an unexpanded hub.

When the first issue can't be read, the command prints the error code on stderr, prints no report, and exits with `1`. Depth boundaries appear in the coverage but don't make it partial.

| Flag              | Default | Range     |
| ----------------- | ------- | --------- |
| `--depth`         | 1       | 0 to 8    |
| `--max-nodes`     | 80      | 1 to 1000 |
| `--hub-threshold` | 12      | 1 to 1000 |
| `--concurrency`   | 4       | 1 to 16   |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)