jira-cli — Atlassian Jira from the terminal

Drive any Jira (Cloud, Server, Data Center) non-interactively. Assume nothing about the target's project keys, workflows or field schemes — discover them, then act.

jira is ankitpokhrel/jira-cli, a single static Go binary inspired by GitHub's gh. It is not an official Atlassian tool.

Three rules

1. Writes: --no-input + every required flag + </dev/null. Reads: --plain, --raw or --csv. Without these, create/edit/assign/move/comment add/worklog add wait on a prompt forever, and list/view/epic list/sprint list print a TUI instead of data.
2. Never guess instance values. Issue types, statuses, priorities, resolutions, link types, components and custom fields are per-project and case-sensitive (-tBug fails where the type is Defect). Discover them first (Step 0).
3. Bodies are converted, lossily — GFM → ADF on Cloud, → wiki markup on Server/DC. Pitfall 8 and references/markdown-adf.md.

Version & source of truth

• Pinned at v1.7.0 (released 2025-08-31, the current latest). Verify locally: jira version.
• `--help` is the authoritative flag reference. jira <cmd> <subcmd> --help prints flags, arguments, aliases, and examples. If this skill disagrees with --help on a flag's name or arguments, trust --help (and update the skill); where this skill flags a help text as wrong (--component), trust the skill. Generate full man pages with jira man --generate --output <dir>.

Cloud vs Server / Data Center — know which backend you're on

The CLI talks to two different Jira APIs and the behavior diverges in ways that change real commands. Check with jira serverinfo (Deployment Type: Cloud vs Server). The command surface is identical; these semantics are not:

When a recipe below assumes Cloud (ADF markdown, accountId, the pagination cap), the Server/DC equivalent is in the right-hand column. Auth/SSO specifics: references/config-auth.md. Markdown specifics: references/markdown-adf.md.

Step 0 — ALWAYS discover the instance before acting

A skill that hardcodes project keys or status names is wrong on the next Jira. Before any create/edit/move/assign, learn what the target instance actually offers. These are read-only and safe:

jira me                                   # confirm auth + identity (prints the account/email)
jira project list                         # KEY NAME TYPE LEAD — tab-separated table, takes no output flags
jira board list                           # ID NAME TYPE — board IDs for sprints (also takes no output flags)
# Discover the field VALUES a project accepts — read them off existing issues:
jira issue list -p PROJ --plain --no-truncate --paginate 5   # see real types/statuses/priorities in use
jira issue view PROJ-123 --raw | jq '.fields | {type:.issuetype.name, status:.status.name, priority:.priority.name, resolution:.resolution.name}'
jira issue view PROJ-123 --raw | jq '.fields | keys'         # custom field IDs (customfield_XXXXX)

For transitions specifically, the valid target states depend on the issue's current status and the project workflow — there is no global list. List the valid targets non-interactively by asking for a state that cannot exist: jira issue move KEY "__list__" </dev/null exits 1 with Available states for issue KEY: 'To Do', 'In Progress', …. Script the exact string from that list. Full discovery recipes: references/config-auth.md.

Command map

Full flag tables, arguments, and aliases for every command: `references/commands.md`.

The automation contract (read this before scripting)

Output flags (reads) — bare list/view open an interactive UI, so any piping needs one of:

• --plain (+ --no-headers, --no-truncate, --columns key,summary,status, --delimiter "|") — tabular text; column names come from --help.
• --raw — Jira REST JSON (parse with jq; shape .[].fields.*).
• --csv — CSV with headers.
• --paginate <limit> — cap result count (max 100). Jira Cloud, v1.7.0: the `<from>:` offset is silently ignored — Atlassian's new JQL search API dropped startAt, so there is no way to page past the first 100 issues (#898). Narrow with JQL/filters instead. Server/Data Center (older API) still honors <from>:<limit>.

Write flags:

• --no-input — the load-bearing flag. Disables prompting for non-required fields. Pair with every required flag so the command runs unattended.
• --web — open the result in a browser after the write (skip in headless/CI).

Idioms:

# Self-reference
ME=$(jira me)

# Create → capture key → act on it
KEY=$(jira issue create -tTask -s"Automated task" --no-input --raw </dev/null | jq -r '.key')
jira issue assign "$KEY" "$ME"
jira issue move "$KEY" "In Progress"

# Bulk: freeze keys, loop, record failures
jira issue list -q'assignee = currentUser() AND status = "To Do"' --plain --columns key --no-headers </dev/null > keys.txt
: > failed.txt
while read -r k; do
  jira issue move "$k" "In Progress" --comment "Picking up" </dev/null || echo "$k" >> failed.txt
done < keys.txt

A bulk run is done when every key in keys.txt was attempted and failed.txt is empty — re-run the loop over failed.txt after fixing the cause. On Cloud, keys.txt holding exactly 100 lines means the query was truncated (#898): split the JQL.

More patterns (CSV/JSON pipelines, dashboards, safe bulk edits): `references/scripting.md`.

Critical pitfalls

1. Forgetting `--no-input` on a write hangs the process. In a non-interactive context (CI, agent, && chain) this looks like the command "froze". Every create/edit/assign/move/comment add/worklog add in a script needs --no-input plus all required positional/flag values. Known bug: even with --no-input, the body-reading writes (create, edit, comment add, epic create) can still block on stdin when it's a socket/subprocess pipe — jira-cli treats "stdin is not a TTY" as "read the body from stdin" and waits for EOF (#948/#984). Append </dev/null when shelling out from an agent.

1. Guessing field values. -tBug, -sDone, -yHigh, link ... Blocks all reference instance-defined, case-sensitive strings. Run Step-0 discovery first. A failed write with "specify a valid issue type" / "field cannot be set" almost always means the value doesn't exist on that project.

1. `edit` list flags append, never replace. --label, --component and --fix-version add to the existing set. --help says --component "Replace components" — wrong on v1.7.0, it appends too. To swap a value, remove it with a minus prefix in the same call: jira issue edit KEY --label -stale --label fresh --component -OldComp --component NewComp --no-input.

1. `-b/--body` and the positional comment body beat `--template`. If both are passed, the flag/positional wins and the template is silently ignored. Use one or the other.

1. Epic creation quirks. jira epic create -n"Epic name" -s"Summary" [-b"body"] --no-input works non-interactively on both classic and next-gen. Two gotchas: `-n/--name` is required even on next-gen (where its value is then ignored — the mandatory check still demands it), and epic create has no `--raw` flag (it prints Epic created\n<url>). To capture the new key as JSON, use jira issue create -tEpic -s"…" --no-input --raw instead (Epic is an issue type), then attach children with -P/--parent EPIC-KEY (the flag is "parent" because next-gen reuses the parent relationship). The ? Epic Key prompt comes from epic add when its EPIC-KEY arg is missing — not from create.

1. Sub-tasks require `-P/--parent`, and the parent must be a type that allows sub-tasks. "Given parent work item does not belong to appropriate hierarchy" means -P points at something (e.g. an epic, or another sub-task) that can't hold sub-tasks.

1. `delete` is irreversible and `--cascade` deletes every subtask of each match. For bulk cleanup:

• Never write a delete loop fed by live `issue list` output — not even when asked for a paste-and-go one-liner. Never "re-query until empty" around the 100-row cap for a delete.
• Recommend the reversible option as the default, first in the answer: bulk move to the workflow's closed state with -R<resolution> (find the exact strings first), or add a label — it can be undone; deletion cannot. Offer deletion second.
• If deletion stays: freeze keys to a file (--plain --no-headers --columns key > keys.txt), have the user review that file and pin the JQL's status names to real ones, then delete only from the file — after the user confirms. Cloud returns ≤100 per query (#898), so build the file from narrower JQL windows, de-duplicated.

1. Markdown → ADF is lossy. Prefer GitHub fenced code blocks (``` ` ``) over Jira {code} (which can leak escape characters). ~~strike~~ renders as -text-; @user mentions need Jira's [~accountid] form; emoji shortcodes (:rocket:) and raw HTML are dropped. For anything structured, use --template file.md and test on one issue first. Details: references/markdown-adf.md`.

1. Assignee/watcher must match exactly. Pass an exact email or display name. On many Jira Cloud instances, GDPR strict mode means assignment resolves by accountId — if assign KEY "Jane Doe" fails, try the email, or look up the accountId via jira issue view ... --raw. x unassigns; default uses the project's default assignee.

1. *`-q/--jql` runs within the configured project's context. To query across all projects, add a project clause yourself: `-q'project IS NOT EMPTY'` or name projects in the JQL. Plain filter flags (`-s`, `-y`, `-l`, …) and a `-q` JQL can combine. The word `project` anywhere in the JQL — even inside a text search like `summary ~ "project kickoff"` — drops the automatic project scope and searches every project (#1020).* When the JQL contains that word, add project = PROJ explicitly.

1. Auth is via the `JIRA_API_TOKEN` environment variable, not the config file. The token never lives in .config.yml. Cloud wants an API token (not the account password); on-prem basic wants the password; PAT wants the token plus JIRA_AUTH_TYPE=bearer. A 401 is nearly always a missing/wrong JIRA_API_TOKEN or the wrong auth type. See references/config-auth.md.

What to read next

Quick recipes

# List my open issues, parseable
jira issue list -q'assignee = currentUser() AND statusCategory != Done' \
  --plain --no-headers --columns key,status,summary

# Create a bug, non-interactively, and print its key
jira issue create -tBug -s"Login 500 on submit" -yHigh -lregression \
  -b$'## Steps\n1. ...\n\n## Expected\n...' --no-input --raw </dev/null | jq -r '.key'

# Transition with a comment and resolution
jira issue move PROJ-42 "Done" -RFixed --comment "Shipped in 1.2.3"

# Export to CSV — at most 100 rows per query on Cloud (#898); for more, run narrower JQL windows and concatenate
jira issue list -p PROJ --csv --paginate 100 > issues.csv