narumiruna/using-jira-cli

Jira CLI

Overview

Use jira for Jira work from the terminal. Prefer read-only discovery first, script-friendly output for agents, and explicit confirmation before changing Jira state.

Safety Rules

• Do not print or store Jira tokens. Use JIRA_API_TOKEN, .netrc, keychain, or the user's existing shell setup.
• Check the installed command help when flags matter: jira --help, then jira <resource> <command> --help.
• Prefer non-interactive output in agent runs when the command supports it: --plain, --raw, --csv, --no-headers, and --columns.
• Prefer --no-input only when all required write parameters are known.
• Before create/edit/move/assign/delete/comment/worklog/link operations, show the exact command and ask for confirmation unless the user already authorized that exact mutation.
• Always confirm before jira issue delete, even if the user asked generally.

Setup Check

command -v jira
jira version
jira me

If jira is not installed, tell the user to install JiraCLI first and point them to https://github.com/ankitpokhrel/jira-cli/wiki/Installation.

If jira is installed but not configured:

export JIRA_API_TOKEN=...     # never echo the value
jira init                     # Cloud or Local setup

For on-prem Personal Access Token auth, set:

export JIRA_AUTH_TYPE=bearer
export JIRA_API_TOKEN=...

For multiple Jira configs, use one of:

JIRA_CONFIG_FILE=./jira-config.yaml jira issue list --plain
jira issue list -c ./jira-config.yaml --plain

Read Workflow

1. Identify context with read-only commands:

   jira project list
   jira board list
   jira me
   

2. Search issues with filters or JQL:

   jira issue list --plain --columns key,status,assignee,summary --no-headers
   jira issue list -a"[email protected]" -s"In Progress" --plain
   jira issue list -q "summary ~ cli" --plain
   jira issue list --raw
   

3. Inspect the ticket before proposing changes:

   jira issue view ISSUE-1
   jira issue view ISSUE-1 --comments 5
   

Write Workflow

Use explicit issue keys and quote values with spaces. Prefix issue titles/summaries with the project name when known: [<project_name>] <title/summary>.

Examples:

• Known project name: [skills] add using-jira-cli skill
• Unknown project name: add using-jira-cli skill

For issue descriptions, use this compact template unless the user provides another one:

## Summary
<what changes>

## Acceptance Criteria
- [ ] <done condition>

## Optional
- Context: <why now>
- Scope: <in/out of scope>
- Links: <related issue, PR, doc>

# Create
jira issue create -tTask -s"Summary" -b"Description" --no-input
jira issue create -tStory -s"Story summary" -PEPIC-42 --no-input

# Edit
jira issue edit ISSUE-1 -s"New summary" --no-input
jira issue edit ISSUE-1 --label -old-label --label new-label --no-input

# Assign / unassign
jira issue assign ISSUE-1 "[email protected]"
jira issue assign ISSUE-1 x

# Transition
jira issue move ISSUE-1 "In Progress"
jira issue move ISSUE-1 Done -RFixed -a"[email protected]"

# Comments and worklogs
jira issue comment add ISSUE-1 "Comment body"
echo "Long comment" | jira issue comment add ISSUE-1
jira issue worklog add ISSUE-1 "2h" --comment "What changed" --no-input

Use templates or stdin for longer descriptions/comments:

jira issue create --template ./issue-template.md
jira issue comment add ISSUE-1 --template - < ./comment.md

Planning / Agile Commands

# Epics
jira epic list --table --plain
jira epic list EPIC-1 --plain
jira epic create -n"Epic name" -s"Epic summary" --no-input
jira epic add EPIC-1 ISSUE-1 ISSUE-2
jira epic remove ISSUE-1 ISSUE-2

# Sprints
jira sprint list --table --plain
jira sprint list --current --plain
jira sprint list SPRINT_ID -a"[email protected]" --plain
jira sprint add SPRINT_ID ISSUE-1 ISSUE-2

# Releases, projects, boards
jira release list
jira release list --project KEY
jira project list
jira board list

Output Patterns For Scripts

# Stable tabular extraction
jira issue list --plain --columns key,status,assignee,summary --no-headers

# Machine-readable extraction
jira issue list --raw
jira issue list --csv

# Count examples
jira issue list --created month --plain --columns created --no-headers
jira sprint list --table --plain --columns id,name --no-headers

Common Mistakes

• Letting jira issue list open the interactive UI during an automated agent run.
• Adding output flags to commands that do not support them; project list, board list, and release list do not accept --plain in current JiraCLI.
• Mutating the wrong Jira instance because JIRA_CONFIG_FILE or -c was omitted.
• Assuming status, resolution, priority, issue type, or custom field names; discover them with jira ... --help, existing tickets, or Jira config first.
• Using unquoted shell arguments for statuses or summaries with spaces.
• Adding token values to chat, logs, shell history, or repository files.