jira

Minimal CLI for querying Jira Cloud.

Install

just install    # builds and copies to /usr/local/bin/

Or build manually:

go build -o jira .

Configuration

Read from the environment, overridable per-invocation via global flags:

Env	Flag	Purpose
JIRA_URL	--url	Base URL, e.g. https://acme.atlassian.net
JIRA_USER	--user	Account email
JIRA_TOKEN	--token	API token (id.atlassian.com → Security)
JIRA_PROJECT	--project	Default project key for list
JIRA_TEAM_ID	--team	Default team ID for list

Usage

# Raw JQL
jira search 'assignee = currentUser() AND status != Done'

# Filtered list (uses JIRA_PROJECT / JIRA_TEAM_ID by default)
jira list --assignee me --status "In Progress"
jira list --sprint active
jira list --project FOO --order "created DESC" --limit 100

# Issue details
jira show FOO-123
jira show FOO-123 --no-comments
jira show FOO-123 --json
jira show FOO-123 --web    # open in $BROWSER instead of printing

# Create an issue via $EDITOR template
jira create
jira create --keep    # keep the draft file after creation

# Edit an issue's summary, labels, and description in $EDITOR
jira edit FOO-123

# Move an issue to a workflow state
jira transition Done FOO-123
jira transition "In Progress" FOO-123

# Link two issues (reads left to right)
jira link FOO-1 blocks FOO-2
jira link FOO-1 "is blocked by" FOO-2
jira link FOO-1 "relates to" FOO-2

Commands

• search [--limit N] [--json] JQL... raw JQL query
• list [--assignee] [--status] [--sprint] [--project] [--team] [--order] [--limit] [--json] filtered list
• show [--json] [--no-comments] [--web|-w] KEY issue details; --web opens it in $BROWSER
• create [--keep] open $EDITOR with a template, parse, and create the issue
• edit KEY open the issue's summary, labels, and description in $EDITOR and save changes
• transition STATE KEY move an issue to a workflow state
• link SOURCE RELATION TARGET link two issues by relationship phrase

--assignee me and --sprint active are shortcuts for currentUser() and openSprints().

The link relation is matched against a link type's outward phrase (blocks), inward phrase (is blocked by), or type name (Blocks), so the command reads left to right regardless of which phrase you know. Quote multi-word relations. jira show displays an issue's parent key and its links.

Create template

jira create writes this template to a temp file and opens $EDITOR:

Type: Task          # story, bug, task, epic, subtask
Label:              # comma-separated, e.g. "backend, infra"
Status:             # leave blank for project default
Parent:             # parent issue key, e.g. WORK-123
Link:               # link to other issues, one bullet each:
#   - blocks WORK-2
#   - is blocked by WORK-3

Title:              # required

Description:

Inline # ... comments are stripped from field values. Lines starting with # outside the description are ignored. Everything after the Description: line becomes the issue body verbatim (markdown # headings are preserved).

Status is applied as a post-create transition: the value is matched case-insensitively against the target state name of an available transition. If the status can't be reached, the issue is still created and a warning is printed.

Link takes a bullet list of <relation> <KEY> items (uncomment or add your own under the Link: header). The relation resolves the same way as the link command. Links are applied after the issue is created; the same soft-warning rule as Status applies, so a bad relation or missing target never fails the create. A single inline Link: blocks WORK-2 also works.

Editing and transitions

jira edit KEY opens the issue's summary, labels, and description in $EDITOR and saves back only the fields you change — a deleted field line is left untouched. The description is round-tripped as plain text, so an unedited description is never rewritten (which would flatten rich formatting).

jira transition STATE KEY matches STATE case-insensitively against the target state name of an available transition (the same matching create uses for Status), and errors listing the reachable states when there is no match.