jira-tabbed-tui

A fast, keyboard-driven terminal UI for Jira — your triage board, in the terminal.

jira-tabbed-tui turns your everyday Jira queries into a set of live, tabbed views you can fly through without ever touching the mouse. Define your tabs with JQL, browse issues in a compact table, drill into full detail, and run the common write actions — transition, assign, label, comment — right from the keyboard. It rides on top of the jira CLI for reads and writes and talks to the Jira REST API directly for what the CLI can’t do — notably loading tabs with more than 100 issues.

jira-tabbed-tui demo

The clip above is recorded from the real TUI driven by a mock backend — no live Jira needed. Regenerate it any time with vhs demo/demo.tape (see demo/).


Features

  • Tabbed JQL views — every tab is a saved JQL query; switch with Tab, arrow keys, or a number key. Add, edit, and delete tabs on the fly.
  • Keyboard-first — navigation, filtering, and all write actions are bound to single keys, every binding remappable via config.
  • Rich detail view — description, comments, and links (including subtasks and remote/web links) split across body tabs, with a configurable sidebar of fields.
  • Organised links — the Links tab groups Jira issues, pull requests and other web links, sorts them, shows each linked issue’s type, and shows whether linked GitHub/GitLab pull requests are open, merged or closed. Follow links as deep as you like; a breadcrumb shows where you are.
  • Write actions from the terminal — change status (transitions), assign users, add labels, and post comments without leaving the app. On the Links tab, move or assign the highlighted linked issue without opening it.
  • Copy to clipboard — press Y to pick which column values or issue fields to copy, or grab the issue’s full URL with Y u (see Copying to the clipboard).
  • Fuzzy filtering — instantly narrow the loaded rows with /.
  • Sorting — reorder the current list by any column.
  • ADF rendering — Atlassian Document Format bodies (Jira Cloud) are rendered as readable, styled terminal text; plain-string bodies work too.
  • Every issue, without the wait — a tab shows its first 100 issues at once and loads the rest in the background (up to list.max_issues, 1000 by default), with progress under the list.
  • Smart caching — tab lists are cached for 30 minutes (issue details for 5), so switching tabs is instant. Older lists stay on screen while they refresh in the background (the visible tab refreshes itself once its data is 30 minutes old) and the new rows swap in with the cursor on the same issue; a failed refresh keeps the old data, clearly flagged.
  • Field discovery — dump the field name-to-ID mapping for any issue to build custom columns and sidebars, including customfield_* fields.
  • Open in browser — jump straight to any issue on the web.

Requirements

  • Go 1.25+ (only needed to build from source)
  • The jira CLI (ankitpokhrel/jira-cli), installed, configured, and authenticated. jira-tabbed-tui shells out to it for reads and most writes.
  • A Jira API token, for the REST calls the CLI doesn’t cover (status transitions, assignable-user search, remote links). See Authentication.

Installation

From source

git clone https://github.com/clobrano/jira-tabbed-tui.git
cd jira-tabbed-tui
go build -o jira-tabbed-tui .

Then move the resulting jira-tabbed-tui binary somewhere on your PATH.

With go install

go install github.com/clobrano/jira-tabbed-tui@latest

This installs a binary named jira-tabbed-tui into $(go env GOPATH)/bin.

Getting started

  1. Install and authenticate the jira CLI:

    jira init          # configure server + login
    jira me            # verify authentication works
    
  2. Export your Jira API token (see Authentication):

    export JIRA_API_TOKEN="your-token-here"
    
  3. Run it:

    jira-tabbed-tui
    

    On first launch, if no config file exists, a sensible default is written to ~/.config/jira-tabbed-tui/config.yaml and the app starts with two tabs: Assigned and In Progress.

At startup the app verifies that the CLI binary is on your PATH and runs a cheap jira me auth check, so misconfiguration surfaces immediately with an actionable error rather than a blank screen.

Authentication

Issue details and most writes go through the jira CLI, which manages its own authentication (jira init / jira auth login). Tab lists and a few other operations call the Jira REST API directly and need an API token, resolved in this order:

  1. The JIRA_API_TOKEN environment variable.
  2. The GNOME keyring via secret-tool (looked up as service jira-cli with your login email), if the env var is unset.

The server URL and login email are read from the jira CLI’s config (~/.config/.jira/.config.yml) and can be overridden with backend.url in your config.

Tab lists are loaded with Jira’s search API, asking only for the fields the columns show: /rest/api/3/search/jql on Jira Cloud and /rest/api/2/search on Server/Data Center (picked from jira-cli’s installation setting). Without an API token the app falls back to the jira CLI, which returns at most 100 issues per tab on Jira Cloud; the list then says so.

Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens.

Pull request status (optional)

To show whether linked pull requests are open, merged or closed, the app asks GitHub (api.github.com, or $GITHUB_API_URL / https://HOST/api/v3 for GitHub Enterprise on a github.* host) or GitLab (https://HOST/api/v4). Public repositories work without credentials; for private ones set GITHUB_TOKEN (or GH_TOKEN) and/or GITLAB_TOKEN. Lookups are cached for 5 minutes. If a lookup fails the status is simply left blank.

Configuration

Configuration lives at ~/.config/jira-tabbed-tui/config.yaml by default (override with --config /path/to/config.yaml). The file is created with defaults on first run if it doesn’t exist. Configs from older releases at ~/.config/jira-tui/config.yaml are still picked up when the new file doesn’t exist; move the file to the new location whenever convenient.

backend:
  cli: jira                            # the Jira CLI binary to shell out to
  # url: https://myorg.atlassian.net   # base URL for "open in browser" and REST calls
  # extra_args: []                     # extra args prepended to every CLI invocation

tabs:
  - name: Assigned
    jql: assignee = currentUser()
    # sort: priority   # initial sort field (key, priority, status, assignee, duedate, …)
    # sort_asc: false  # true = ascending, false = descending (default)
    # columns:         # overrides list.columns for this tab only
    #   - field: key
    #     label: ID
    #   - field: summary
    #   - field: priority
  - name: In Progress
    jql: assignee = currentUser() AND status = "In Progress"

list:
  # Built-in fields: key, type, summary, priority, status, assignee,
  #                  duedate, created, updated
  # Any field returned by Jira is also supported, including fixVersions,
  # components, and customfield_* values.
  # `label` overrides the column header; `width` fixes the width in chars.
  # Omit `width` on exactly one column to let it expand and fill the row.
  columns:
    - field: key
      label: ID
    - field: type
    - field: summary
    - field: status
  # max_issues: 1000   # stop loading a tab after this many issues (narrow the JQL for more)

detail:
  sidebar_width: 33
  sidebar_fields:
    - field: assignee
    - field: reporter
    - field: labels
    - field: duedate
      label: Due

keybindings:
  # All optional — defaults shown. Override any you like.
  transition: m        # change status
  add_labels: L        # add labels (l moves right, like h/j/k)
  add_comment: c       # add a comment
  assign: a            # assign the issue
  open_browser: o      # open in browser
  field_discovery: ctrl+f  # list all fields; ctrl+e edits the highlighted one
  force_refresh: r     # refresh the current tab
  help: "?"            # toggle the help overlay
  sort: s              # open the sort picker (list view)
  copy: Y              # copy fields / URL to the clipboard
  edit_jql: e          # edit the tab's JQL (Search tab: type a query)

Custom fields in the sidebar

The sidebar accepts any Jira field name — built-ins like assignee, reporter, labels, duedate, priority, status, fixVersions, components, parent, and issuetype, as well as any customfield_* field. Use the fields command to discover the IDs of custom fields:

jira-tabbed-tui fields PROJ-123

This prints a field-name-to-ID mapping for the given issue (no TUI), which you can paste straight into your list.columns or detail.sidebar_fields.

Usage

Launch with jira-tabbed-tui. Press ? at any time for the context-sensitive keybindings overlay.

The title bar at the top shows the Jira server and the signed-in user, how many issues the current tab holds with a colour-coded count per status, and on the right how fresh the data is and when it refreshes itself (updated 2m ago · auto-refresh in 28m · r refresh), the progress of a background refresh (refreshing 300 of 2000…), or refresh failed · data from 6m ago · r retry when a refresh fails and older results are shown. On narrow terminals the less important parts give way first: the tagline, the user, the server, then the rarest statuses. The footer lists the everyday keys for the current view: moving (and, in the task view, back/forward through the issues you followed), opening, and in the list filter, sort and edit JQL. Actions on an issue (change status, assign, comment, labels, copy, open in browser), refresh and quit are listed under ?.

KeyAction
j / ↓Move down
k / ↑Move up
gg / GGo to the top / bottom (rows, links or text)
Tab / h l / ← →Next / previous tab
0–9Jump to tab by index
+Add a new tab
-Delete the current tab
eEdit the current tab’s JQL (Search tab: type a query; Esc leaves the field)
/Fuzzy-filter the loaded rows
EnterOpen issue detail
rRefresh the current tab now
? / EscClose the help overlay
q / Ctrl+CQuit

List view

KeyAction
oOpen in browser (without entering detail)
mMove status
aAssign issue
YCopy column values / issue URL
sSort the list

Detail view

KeyAction
EscBack to list (clears navigation history)
⌫ / Ctrl+oNavigate back in history (returns to the tab and link you left)
Ctrl+iNavigate forward in history
h / l, ← / →Switch body tab (Description / Comments / Links)
EnterOpen the linked issue (on the Links tab)
oOpen in browser
mMove status (of the highlighted linked issue on the Links tab)
aAssign issue (the highlighted linked issue on the Links tab)
LAdd labels
cAdd a comment
YCopy issue fields / URL
rRefresh the issue (and its links) from Jira
Ctrl+fList all fields for the issue
Ctrl+eEdit the highlighted field (in the Fields overlay)

(Action keys reflect the defaults; they follow whatever you set under keybindings in your config.)

Links are grouped and sorted:

  • Jira issues — subtasks, child issues and issue links, sorted by key (PROJ-9 before PROJ-10), with the relationship, the issue type and its status.
  • Pull requests — GitHub pull requests and GitLab merge requests, with their state: open, draft, merged or closed (see Pull request status).
  • Web links — any other remote link, sorted by title.

Enter opens a Jira link in place (or a web link in the browser). Each issue you open this way is added to a history: ⌫/Ctrl+o goes back and Ctrl+i forward, returning to the same tab and highlighted link. Once you are more than one issue deep, a breadcrumb above the header shows the trail and your depth, e.g. depth 2/3 PROJ-1 › PROJ-7 › PROJ-9, with the current issue highlighted and the ones you can go forward to dimmed.

Copying to the clipboard

Y opens a picker of what can be copied from the current view:

  • List view — one entry per displayed column, in column order, plus the issue’s full URL.
  • Detail view — the issue’s fields (key, summary, type, status, priority, assignee, dates, your sidebar fields, description), plus the full URL. On the Links tab the highlighted link’s key/URL are offered too.

In the picker, 1–9 copy that entry right away and u copies the URL. Space marks several entries (a marks all) and Enter copies them joined by a space, newline or tab (cycle with Tab); with nothing marked Enter copies the highlighted entry.

The clipboard is written with xclip/xsel/wl-copy (Linux) or pbcopy (macOS); when none is available (e.g. over SSH) the OSC 52 terminal escape sequence is used instead. The URL needs a Jira server, taken from backend.url or jira-cli’s config.

How it works

jira-tabbed-tui is a Bubble Tea application. At a glance:

  • cmd/ — the Cobra command tree: the root command that boots the TUI, plus the fields subcommand.
  • config/ — loading, validating, and defaulting the YAML config.
  • backend/ — everything that talks to Jira: a Runner that shells out to the jira CLI, JSON/ADF parsers, direct REST calls (list search, transitions, assignable users, remote links), and a TTL cache that also holds partially loaded lists and falls back to stale data.
  • model/ — the plain data types (issues, comments, links, transitions, users, fields) shared across the app.
  • tui/ — the Bubble Tea views: tab bar, list, detail view with sidebar, search, status line, and the help overlay.

Reads use jira issue list --raw / jira issue view --raw; writes use jira issue move / edit / assign / comment add. Operations the CLI doesn’t expose fall back to authenticated calls against /rest/api/3/....

Development

go build ./...     # build everything
go test ./...      # run the test suite
go vet ./...       # static checks

The backend ships with a FakeRunner test double so parsing, caching, and command construction can be exercised without a live Jira instance.

Contributing

Issues and pull requests are welcome. If you’re adding a feature, a short note in the PR describing the behavior and any new config keys goes a long way.

License

No license file is currently included in this repository. If you intend to use or distribute this project, please check with the author regarding licensing terms.