changelog

README

jira

Terminal-first Jira CLI for day-to-day developer workflows.

Install

go install github.com/matcra587/jira-cli/cmd/jira@latest

Homebrew and GoReleaser release archives include release version metadata. go install github.com/matcra587/jira-cli/cmd/jira@latest builds from source and reports the module version in jira version (resolved from Go build info; a plain go build reports a commit-derived dev version). Release archives currently target macOS, Linux, and Windows.

See docs/installation.md for release archives, the one-line installer, source builds, and uninstall steps. The examples below assume jira is on PATH.

Quick start

# 1. Create profile metadata
jira config init --no-input \
  --base-url https://company.atlassian.net \
  --email dev@example.com

# 2. Store an API token and verify Jira accepts it
jira auth login
jira auth status

# 3. List your issues
jira issue list

For issue creation, editing, comments, and ADF payloads, start with docs/issue/read.md. For classic API tokens, auth backends, and 1Password, use docs/auth.md.

Configuration

Configuration lives in ~/.config/jira-cli/config.toml (on Windows, %AppData%\jira-cli\config.toml). Use metadata-only profiles; credentials belong in the OS keychain, 1Password, or environment fallbacks.

jira config init --no-input \
  --profile default \
  --base-url https://company.atlassian.net \
  --email dev@example.com

config init requires both --base-url and --email; omitting either exits before writing the config file.

Auth

jira auth status
jira auth login
jira auth token

auth login uses auth_type = token (the only supported value); it covers both classic and scoped (granular) API tokens. Unsupported auth types are rejected instead of being stored as fake authenticated profiles.

The 1Password backend uses the Go SDK when onepassword_account is configured for desktop-app auth or OP_SERVICE_ACCOUNT_TOKEN is present for service-account auth. macOS, Linux, and Windows release archives are built without CGO, so use a CGO-enabled source build for 1Password-backed profiles.

For desktop-app auth, 1Password must be signed in and allowed to serve SDK requests before jira can read items. In the 1Password app, open Settings > Developer and enable Integrate with other apps. If you want biometric approval, also enable the OS unlock option under Settings > Security. Desktop-app SDK authorization is per account and per process, so separate jira invocations may prompt separately even when the app is unlocked. Use the system keychain backend for prompt-free day-to-day commands.

Further reading:

• 1Password SDK desktop app integration

[[profiles]]
name = "work"
base_url = "https://company.atlassian.net"
auth_type = "token"
email = "dev@example.com"
secret_backend = "1password"
onepassword_account = "Team"
vault = "Engineering"
item = "jira-cli-work"

Token support

jira talks to Jira Cloud only; Server/Data Center are not supported. The CLI supports both classic Atlassian API tokens and scoped (granular) API tokens, and jira auth login detects which you have automatically — there are no scoped-specific flags. Classic tokens hit the site REST base URL (https://your-site.atlassian.net/...); scoped tokens are auto-detected at login (verified against the site, then the gateway) and routed through Atlassian's gateway (https://api.atlassian.com/ex/jira/<cloudId>/...) via a stored cloud_id. See docs/auth.md.

TUI

[!WARNING] The dashboard is in alpha: actively developed, and keybindings or configuration may still change between releases. The headless CLI commands remain the stable surface for scripts and agents.

Run jira -i or jira tui in a terminal for a persistent, full-screen dashboard: tabbed JQL views with live counts, quick-filter lenses, an always-visible issue preview, single-key triage verbs with optimistic updates, multi-select bulk actions, and a JQL search workbench with autocomplete and saved-query presets. Tabs, lenses, sections, the preview dock and every keybinding are configurable under [tui] in config.toml.

Core keys: j/k move, enter open, / filter, f facet, ]/[ lens, t transition, a/A assign, c comment, e edit, w worklog, space select, ctrl+o recent, ? help, q quit.

See the TUI documentation for the full tour and configuration reference. Prefer the regular CLI commands for scripts and agent workflows.

Output

Non-TTY and agent environments emit JSON without prompts. Pick a mode explicitly with --output; valid values are auto, human, json, and compact.

jira issue list --output=json
jira issue create --json-input payload.json --no-input --dry-run --output=json
jira agent schema --output=compact

Where payload.json is at minimum:

{"summary": "Fix login", "project_key": "PROJ", "issue_type": "Task"}

project_key and issue_type are required under --no-input. See the embedded agent guide (jira agent guide) for richer payload shapes including ADF descriptions and customfields.

For agent-facing contracts, use the embedded references instead of copying recipes from the README:

jira agent guide
jira agent schema --output=compact
jira agent adf-matrix --output=json
jira agent fieldtypes --output=json

TTY commands render successful results through clog rich output:

INF ℹ️ listed issues count=0 detail=false

Use --output=compact for jq-friendly data-only JSON and --output=human to force clog rich text.

Commands

Command	Docs
auth, config	auth.md, config.md
issue, epic	issue/read.md, epic.md
jql, search	jql.md, search.md
worklog	worklog.md
cache	cache.md
alias	alias.md
agent	agent.md
output, troubleshooting	output.md, troubleshooting.md

JQL

jira issue list defaults to recently-updated issues (updated >= -365d ORDER BY updated DESC). Override with --jql or builder flags:

jira issue list
jira issue list --jql 'project = PROJ AND status = "In Progress"'
jira jql build --project PROJ --assignee me --status "In Progress"

See docs/jql.md for supported builder flags and Atlassian JQL references.

Aliases

jira alias set mine -- issue list --assignee me
jira alias set inbox "issue list --assignee me"
jira alias list
jira alias import aliases.yml
jira alias delete mine

Documentation

Overview

Package changelog embeds jira-cli's own release notes so the binary can show its changelog without reaching the network. The per-change fragments under .changes/ are batched by changie into one Markdown file per version; those files (and the changelog header) are compiled in here, parsed into structured releases, and assembled on demand. This is jira-cli's changelog surfaced to its users, and is unrelated to the `jira release-notes` view of a Jira project's issues.

Index

• func Full() string
• func Header() string
• type Release
  • func Find(query string) (Release, bool)
  • func Releases() []Release
• type Section

Functions

func Full

func Full() string

Full assembles the complete changelog — the header followed by every version, newest first — mirroring the merged CHANGELOG.md.

func Header

func Header() string

Header returns the changelog preamble.

Types

type Release

type Release struct {
	// Version is the semantic version without the leading v, e.g. "0.7.7".
	Version string `json:"version"`
	// Tag is the git tag form, e.g. "v0.7.7".
	Tag string `json:"tag"`
	// URL links to the release, taken from the version heading.
	URL string `json:"url,omitempty"`
	// Date is the release date as written in the heading, e.g. "2026-07-05".
	Date string `json:"date,omitempty"`
	// Sections are the change groups (Added, Fixed, …) in file order.
	Sections []Section `json:"sections"`
	// Markdown is the version's notes exactly as batched. It drives the human
	// renderer and is deliberately excluded from JSON.
	Markdown string `json:"-"`
}

Release is one released version's notes, parsed into structured sections.

func Find

func Find(query string) (Release, bool)

Find returns the notes for a single version. The query may carry a leading v or not ("0.7.7" and "v0.7.7" both match).

func Releases

func Releases() []Release

Releases returns every released version, newest first. The returned slice is shared across calls and must be treated as read-only.

type Section

type Section struct {
	Kind    string   `json:"kind"`
	Changes []string `json:"changes"`
}

Section is one change group within a release, e.g. "Fixed".