jira-cli

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 may report dev or git-derived metadata in jira version. Release archives currently target macOS and Linux.

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/issues.md. For classic API tokens, auth backends, and 1Password, use docs/auth.md.

Configuration

Configuration lives in ~/.config/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

Use token, basic, pat, or mtls for auth login. 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 and Linux 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. Today the CLI supports classic Atlassian API tokens. Scoped API tokens are planned for a future auth update because they require Atlassian's gateway URL (https://api.atlassian.com/ex/jira/<cloudId>/...) instead of the normal https://your-site.atlassian.net/... REST base URL.

TUI

Run jira -i or jira tui in a terminal. The dashboard uses vim-style navigation and keeps running until q.

The TUI is still in active development. Use it for interactive daily navigation; prefer regular CLI commands for scripts and agent workflows.

Core keys: j/k, /, Enter, e, m, c, w, n, r, P, ?, q.

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