changelog

package module

v0.14.2 Latest Latest Go to latest Published: Jul 23, 2026 License: MIT Imports: 6 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/matcra587/jira-cli

Links

Open Source Insights

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.

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

Use --output=compact for jq-friendly data-only JSON and --output=human to force clog rich text. A built-in --jq EXPR filters the JSON in-process (no external jq needed) — strings print raw, other results print as JSON per line.

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

Constants ¶

This section is empty.

Variables ¶

This section is empty.

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".

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
check-changie command Command check-changie fails a feat/fix commit that ships no changelog fragment (and no `Changelog: skip` trailer), so nothing user-facing is missed from the release notes.	Command check-changie fails a feat/fix commit that ships no changelog fragment (and no `Changelog: skip` trailer), so nothing user-facing is missed from the release notes.
gen-docs command Command gen-docs renders the jira command tree into Markdown reference pages for the docs site.	Command gen-docs renders the jira command tree into Markdown reference pages for the docs site.
jira command Command jira is the terminal-first CLI for Jira Cloud; it wires the Cobra command tree via internal/cli/root and owns process exit.	Command jira is the terminal-first CLI for Jira Cloud; it wires the Cobra command tree via internal/cli/root and owns process exit.
internal
adf Package adf parses, validates, normalizes, and renders Atlassian Document Format — the JSON rich-text schema behind Jira descriptions, comments, and worklog notes.	Package adf parses, validates, normalizes, and renders Atlassian Document Format — the JSON rich-text schema behind Jira descriptions, comments, and worklog notes.
agentguides Package agentguides embeds and loads the agent workflow guides that docent serves through `jira agent` and `jira guide`.	Package agentguides embeds and loads the agent workflow guides that docent serves through `jira agent` and `jira guide`.
browser Package browser builds Jira web URLs and opens them in the OS default browser.	Package browser builds Jira web URLs and opens them in the OS default browser.
cache Package cache is a tiny per-profile JSON file store for Jira metadata (labels, epics, projects, …) that's cheap to look up — used by the `jira cache <resource>` commands and (eventually) by Cobra shell completion functions.	Package cache is a tiny per-profile JSON file store for Jira metadata (labels, epics, projects, …) that's cheap to look up — used by the `jira cache <resource>` commands and (eventually) by Cobra shell completion functions.
cli Package cli is the cobra-free presentation and error layer the command packages share.	Package cli is the cobra-free presentation and error layer the command packages share.
cli/adfcmd Package adfcmd implements the `jira adf` command group: standalone Markdown→ADF conversion and linting, plus the explicitly-lossy ADF→Markdown projection.	Package adfcmd implements the `jira adf` command group: standalone Markdown→ADF conversion and linting, plus the explicitly-lossy ADF→Markdown projection.
cli/adfmode Package adfmode resolves the strict vs best-effort ADF mode for a given CLI invocation, applying both the precedence ladder and per-path defaults.	Package adfmode resolves the strict vs best-effort ADF mode for a given CLI invocation, applying both the precedence ladder and per-path defaults.
cli/agent Package agent hosts the registry commands mounted under docent's `jira agent` group — adf-matrix and fieldtypes, the machine-readable ADF and custom-field support registries.	Package agent hosts the registry commands mounted under docent's `jira agent` group — adf-matrix and fieldtypes, the machine-readable ADF and custom-field support registries.
cli/alias Package alias hosts the `jira alias` command group for managing the user-defined command aliases stored in the config file.	Package alias hosts the `jira alias` command group for managing the user-defined command aliases stored in the config file.
cli/auth Package auth hosts the `jira auth` command group for managing Jira credentials and the active profile.	Package auth hosts the `jira auth` command group for managing Jira credentials and the active profile.
cli/boards Package boards hosts the `jira boards` command tree.	Package boards hosts the `jira boards` command tree.
cli/boardscope Package boardscope resolves the `--board NAME` / `--board-id N` flag pair against the local board cache and renders the result into JQL clauses and envelope data.	Package boardscope resolves the `--board NAME` / `--board-id N` flag pair against the local board cache and renders the result into JQL clauses and envelope data.
cli/cache Package cache hosts the `jira cache` command group: per-resource primers that fetch Jira metadata into the per-profile cache, plus housekeeping (clear, refresh).	Package cache hosts the `jira cache` command group: per-resource primers that fetch Jira metadata into the per-profile cache, plus housekeeping (clear, refresh).
cli/cache/registry Package registry is the single source of truth for the cacheable Jira metadata resources: their identity, default freshness window, and fetch.	Package registry is the single source of truth for the cacheable Jira metadata resources: their identity, default freshness window, and fetch.
cli/cmdutil Package cmdutil holds the cross-cutting helper layer shared by every jira-cli command: envelope writers, client/profile accessors, output-mode resolution, mutation gates, the credential-warning sink, and small generic value helpers.	Package cmdutil holds the cross-cutting helper layer shared by every jira-cli command: envelope writers, client/profile accessors, output-mode resolution, mutation gates, the credential-warning sink, and small generic value helpers.
cli/completion Package completion hosts the `jira completion` command and the dynamic shell-completion emitters.	Package completion hosts the `jira completion` command and the dynamic shell-completion emitters.
cli/config Package config implements the `jira config` cobra command tree, which manages the local configuration file, profiles, and theme settings.	Package config implements the `jira config` cobra command tree, which manages the local configuration file, profiles, and theme settings.
cli/epic Package epic hosts the `jira epic` command group: list, board, add, and remove for epic-to-issue membership.	Package epic hosts the `jira epic` command group: list, board, add, and remove for epic-to-issue membership.
cli/issue Package issue hosts the `jira issue` command group — the CLI's largest verb — covering the issue lifecycle (create, view, list, edit, clone, move, delete, transition) and its sub-resources: comments, attachments, links, watchers, and rank.	Package issue hosts the `jira issue` command group — the CLI's largest verb — covering the issue lifecycle (create, view, list, edit, clone, move, delete, transition) and its sub-resources: comments, attachments, links, watchers, and rank.
cli/jql Package jql hosts the `jira jql` command group for building, validating, and referencing JQL queries — the local query-construction helpers that complement the search commands.	Package jql hosts the `jira jql` command group for building, validating, and referencing JQL queries — the local query-construction helpers that complement the search commands.
cli/me Package me hosts the `jira me` command, a short alias for the identity portion of `jira auth whoami` that prints the active profile's Jira identity.	Package me hosts the `jira me` command, a short alias for the identity portion of `jira auth whoami` that prints the active profile's Jira identity.
cli/releasenotes Package releasenotes implements `jira release-notes`, which prints jira-cli's own changelog — embedded in the binary — so a user can see what changed in the tool without opening GitHub or the docs site.	Package releasenotes implements `jira release-notes`, which prints jira-cli's own changelog — embedded in the binary — so a user can see what changed in the tool without opening GitHub or the docs site.
cli/root Package root assembles the CLI's top-level cobra command: the persistent flags, help renderer, PersistentPreRunE (config, logging, output-mode resolution), and the subcommand tree, plus the completion-preflight seam and Execute.	Package root assembles the CLI's top-level cobra command: the persistent flags, help renderer, PersistentPreRunE (config, logging, output-mode resolution), and the subcommand tree, plus the completion-preflight seam and Execute.
cli/runtime Package runtime is the dependency boundary between the binary shell in cmd/jira and the command implementations.	Package runtime is the dependency boundary between the binary shell in cmd/jira and the command implementations.
cli/schema Package schema builds the machine-readable command and output schemas that `jira agent schema` emits and the docs generator reads.	Package schema builds the machine-readable command and output schemas that `jira agent schema` emits and the docs generator reads.
cli/search Package search hosts the `jira search` command group for running Jira searches — ad-hoc JQL and the saved named queries from the config's queries path.	Package search hosts the `jira search` command group for running Jira searches — ad-hoc JQL and the saved named queries from the config's queries path.
cli/startup Package startup parses jira's global flags and first subcommand out of the raw argv before cobra runs.	Package startup parses jira's global flags and first subcommand out of the raw argv before cobra runs.
cli/stdin Package stdin is the ONLY place in the source tree allowed to read os.Stdin.	Package stdin is the ONLY place in the source tree allowed to read os.Stdin.
cli/tui Package tui wires the `jira tui` command to the section-based dashboard.	Package tui wires the `jira tui` command to the section-based dashboard.
cli/update Package update implements the `jira update` cobra command, which self-updates a release-archive binary in place and points Scoop and go-install binaries at the command their channel manages updates with.	Package update implements the `jira update` cobra command, which self-updates a release-archive binary in place and points Scoop and go-install binaries at the command their channel manages updates with.
cli/user Package user hosts the `jira user` command group.	Package user hosts the `jira user` command group.
cli/version Package version implements the `jira version` cobra command: a bare version string for humans (and tooling that probes `<binary> version`), a labeled metadata block behind --detailed, and the structured envelope in machine modes.	Package version implements the `jira version` cobra command: a bare version string for humans (and tooling that probes `<binary> version`), a labeled metadata block behind --detailed, and the structured envelope in machine modes.
cli/worklog Package worklog hosts the `jira worklog` command group for adding and listing work logged against an issue.	Package worklog hosts the `jira worklog` command group for adding and listing work logged against an issue.
config Package config is the layered configuration store for jira-cli: a koanf v2 loader over defaults, a TOML file, and a JIRA_* environment overlay (last wins), plus the profile model and the credential backends profiles point at.	Package config is the layered configuration store for jira-cli: a koanf v2 loader over defaults, a TOML file, and a JIRA_* environment overlay (last wins), plus the profile model and the credential backends profiles point at.
docs Package docs renders a Cobra command tree to byte-stable Markdown for the jira-cli documentation site.	Package docs renders a Cobra command tree to byte-stable Markdown for the jira-cli documentation site.