jirallm

Export Jira Cloud issues as LLM-ready context bundles — markdown, attachments, and deduplicated video frames.

Why it exists

Pasting Jira tickets into an LLM is painful: descriptions are ADF (Atlassian Document Format), comments live in a separate API, attachments are URLs behind auth, and video recordings are useless to a text model. jirallm turns a Jira issue into a self-contained folder of clean markdown plus extracted media — ready to drop into Claude, ChatGPT, Cursor, or any RAG pipeline.

It exists because every team that uses Jira + LLMs ends up writing the same brittle scraping script. This is the version you wish you had.

Features

• Export one or more issues by key into a structured folder
• Renders Jira ADF descriptions and comments to clean Markdown
• Downloads all attachments with original filenames (auth handled)
• Extracts frames from attached videos via ffmpeg and deduplicates near-identical frames using pixelmatch
• Exports the Confluence pages an issue links to (with the images and files they show) next to the issues, and points the links at the local copies
• Produces an index.md summary per issue, ready to paste into an LLM context window
• Works as a CLI (jirallm) and as a programmatic library
• TypeScript-first, ESM, zero hidden globals

Requirements

• Node.js >= 20
• ffmpeg on your PATH — only required if you export issues with video attachments. You can also run jirallm setup to install it for you (and jirallm init will offer to do this automatically when you opt into video frames).
• A Jira Cloud API token

Installation

# Global CLI (built release branch, includes the web UI and the Claude Code plugin files)
npm install -g github:hung-duongquang/jirallm#release

Setup guide for colleagues: https://hung-duongquang.github.io/jirallm/?setup

Updating

jirallm checks the release branch once a day in the background and prints a notice on the next run. To upgrade:

jirallm upgrade           # reinstalls from github:hung-duongquang/jirallm#release (npm / pnpm / yarn)
jirallm upgrade --check   # only report whether a newer release exists

Running the install command again does the same.

Configuration

The recommended way to configure jirallm is the interactive wizard:

jirallm init

It prompts for everything, writes an org + project entry to ~/.config/jirallm/config.toml, and stores the API token in your OS keychain (macOS Keychain / libsecret / Windows Credential Manager) — never on disk.

Run jirallm init again any time you want to add another organization or add a new project to an existing organization — the wizard detects existing config and lets you pick "Create a new organization" or "Add a project to ".

If you enable video frame extraction during init and ffmpeg isn't on your PATH, init will offer to run jirallm setup for you. You can also run it manually any time, or use jirallm setup --bundled to install a self-contained ffmpeg via npm without touching your system.

Organizations and projects

Configuration is two levels: an organization owns the connection (Jira instance, account email, API token); each org has one or more projects that share those credentials and only differ by project key (and optionally output directory).

# ~/.config/jirallm/config.toml

[orgs.widgets]
base_url         = "https://widgets.atlassian.net"
user_email       = "[email protected]"
include_subtasks = true

[orgs.widgets.video_frames]
enabled    = true
fps        = 5
max_frames = 10

[orgs.widgets.projects.WID]
output_dir = "~/jira/widgets"

[orgs.acme]
base_url   = "https://acme.atlassian.net"
user_email = "[email protected]"
# Confluence sites whose pages linked from issues are exported (default: the Jira site).
# The Jira API token is sent to these sites, so list only your own.
confluence_urls = ["https://acme-wiki.atlassian.net"]

# Three projects share the same Jira instance + token
[orgs.acme.projects.PROJ]
output_dir = "~/jira/acme/proj"

[orgs.acme.projects.DOCS]
output_dir = "~/jira/acme/docs"

[orgs.acme.projects.LIB]

Most invocations are just the issue key — jirallm looks up the org by the project prefix:

jirallm PROJ-7              # auto-resolves to the org that owns PROJ
jirallm acme/PROJ-7         # disambiguate if multiple orgs have a PROJ project
jirallm --org acme PROJ-7   # explicit override

If a project key exists in more than one org and you didn't qualify it, you'll get an interactive picker (TTY) or an error suggesting --org / org/KEY (non-TTY).

Useful subcommands:

jirallm orgs list                   # show orgs, projects, and token status
jirallm auth set --org acme         # replace stored token (per organization)
jirallm auth rm  --org acme         # remove stored token

Selection precedence

1. --org flag
2. org/ prefix on the issue key (e.g. acme/PROJ-7)
3. Auto-resolved from the project prefix when only one configured org owns it

CLI flags (--base-url, --output-dir, --fps, …) override whatever the resolved config produces.

Export field selection

The frontmatter fields written by jirallm <key> / jirallm export default to the default preset. An org can pin its own base set, and declare the custom fields it cares about:

[orgs.acme.export.fields]
preset  = "minimal"          # "all" | "default" | "minimal" — optional
include = ["labels"]         # extra fields on top of the preset
exclude = ["subtasks"]       # fields to drop

[orgs.acme.export.custom_fields.team]
id   = "customfield_10050"
type = "select"

This is the beginning of the README. Read the rest at the original. Read the full README ↗