Overview¶

jira is a terminal-first Jira CLI for developers and agents. One binary, machine-readable JSON envelopes, every command driveable from flags, stdin, JSON input files, or environment variables. The binary is jira; the repo and Go module are jira-cli.

Quick start¶

brew install matcra587/tap/jira                    # 1. install
jira config init --base-url https://example.atlassian.net --email john.doe@example.com
jira auth login                                    # 2. authenticate (interactive on a TTY)
jira issue list --assignee me                      # 3. first read

Other install paths (one-line installer, go install, pre-built tarballs) live in Installation. For the headless flow (CI / scripted bootstrap), see auth login.

What it does¶

Read and search issues, comments, attachments, watchers, worklog. → Issues, Search, JQL
Create, edit, transition, link issues with rich-text ADF payloads and dry-run preview. → Issues
Cache project, field, board, label, and link-type metadata so completion and validation don't pay a round trip. → Cache
Stream structured output for scripts and CI. JSON envelope with ok / meta / data / errors[] / warnings[], typed exit codes. → Output
Author rich text in Atlassian Document Format directly, with strict validation before submission. → ADF
Drive from an LLM agent. Machine-readable command schema, per-workflow runbooks, live ADF coverage matrix. → Agents

Common commands¶

I want to…	Command
Authenticate against a Jira tenant	`jira auth login`
Switch between configured profiles	`jira auth switch` or `--profile/-P`
Find issues by filter flags	`jira issue list`
Find issues with raw JQL	`jira search jql`
Save and re-run a JQL query	`jira search saved`
Build JQL without memorising operators	`jira jql build`
Preview a mutation without contacting Jira	`--dry-run` on any mutating command
Apply a batch of edits from a file	`--json-input <file>`
Cache project / field / board metadata	`jira cache <resource>`
Store credentials in 1Password	`jira auth login --backend 1password`
Get a machine-readable command tree	`jira agent schema`
Get an LLM-readable runbook	`jira agent guide <slug>`
Log time spent on an issue	`jira worklog add`
Browse epics or attach an issue to one	`jira epic`
Shorten a long command into a name	`jira alias set`
Identify the active profile and user	`jira me`
Correlate a CLI invocation with Jira logs	`--output=json`, then `meta.request_id`

jira tui is experimental

The persistent dashboard (jira tui / jira -i) ships with the binary but isn't actively developed. For day-to-day work the headless commands above are the supported surface.

Output modes¶

--output (default auto) is the single shape control. On a TTY without an agent it renders human-readable clog output; piped or under a detected agent / CI environment (CLAUDECODE, CURSOR_TERMINAL, GITHUB_ACTIONS, etc.) it switches to compact JSON. The full envelope shape, every per-command example, and the exit-code taxonomy live on Output.

Where to next¶

Install

Platform-specific paths, the one-line installer, version pinning, and uninstall.

Read more →
Authenticate

OS keyring and 1Password backends, the JIRA_TOKEN_<PROFILE> override, credential precedence, and CI patterns.

Read more →
Configure

Per-profile defaults, multi-profile setup, aliases, themes, env vars, and the full config.toml reference.

Read more →
For agents

Machine-readable command schema, per-workflow runbooks, and the live ADF coverage matrix for structured tool integration.

Read more →