Jira CLI Setup and Usage

This skill provides instructions for installing and using the Jira CLI tool to interact with Jira from the command line.

Quick Reference: Common Pitfalls to Avoid

Before diving into detailed commands, be aware of these critical points:

Time Tracking: MUST use jira issue worklog add ISSUE "1m" --new-estimate "1h" - DO NOT use --custom for time tracking
Cannot log 0m: Logging "0m" causes server errors - always log at least "1m"
Status Names Vary: "Done" may not exist - use exact status name from error message (e.g., "Resolved", "Closed")
--no-input Support: Not all commands support --no-input:
- ✓ Supported: issue edit, issue worklog add
- ✗ Not supported: issue move, view/list commands
Environment Setup: Test jira me --plain first - only source ~/.envrc if auth fails

CRITICAL: Environment Setup

Before running any jira-cli commands, check if the user has already configured their environment.

The user may have already:

Installed and configured jira-cli
Set up authentication tokens in environment files (e.g., ~/.envrc, ~/.bashrc, ~/.zshrc)
Configured the Jira CLI in ~/.config/.jira/.config.yml
Exported JIRA_API_TOKEN in their current shell session

Test if jira-cli is already working before sourcing environment files:

# First, try running jira-cli directly
jira me --plain

# If you get authentication errors, THEN check for environment files

Only source environment files if authentication fails:

# If needed, check for and source .envrc conditionally
[ -f ~/.envrc ] && source ~/.envrc 2>/dev/null; jira me --plain

Why this approach:

The JIRA_API_TOKEN environment variable is required for authentication
Users may have already sourced their environment files in the current shell
Users may have tokens configured globally in their shell configuration
Do not assume ~/.envrc needs to be sourced - only do so if authentication fails
The user may have already completed the full setup, so test first before suggesting changes

Troubleshooting steps if commands fail:

First try running jira commands directly (e.g., jira me --plain)
If authentication fails, check if JIRA_API_TOKEN is set: echo $JIRA_API_TOKEN
If not set, then try sourcing common environment files like ~/.envrc
Only suggest installation/configuration if the tool is not found or environment variables cannot be located

IMPORTANT: Preventing Interactive Mode Blocking

ALWAYS use --plain flag (or equivalent non-interactive flags) when running jira-cli commands to prevent the tool from entering interactive mode and blocking execution.

Non-Interactive Flags by Command Type

For listing/viewing commands:

Use --plain to get plain text output instead of interactive UI
Alternative non-interactive flags: --raw (JSON output), --csv (CSV output)

For commands that prompt for input (create, edit, worklog):

Use --no-input to skip interactive prompts
Commands that support --no-input:
- jira issue edit - skips prompts for fields
- jira issue worklog add - skips comment prompt
- Other create/edit commands
Commands that DO NOT support --no-input:
- jira issue move - does not have this flag
- Most viewing/listing commands (use --plain instead)

Important:

If a command doesn't support --no-input, provide all required parameters via flags
If you get "unknown flag: --no-input" error, remove the flag and provide inputs via other flags
Always check error messages for available flags

Examples:

# CORRECT - Non-blocking list commands
jira issue list --plain
jira issue list --raw
jira epic list --plain

# CORRECT - Non-blocking edit/worklog commands
jira issue edit PROJ-123 --custom "field=value" --no-input
jira issue worklog add PROJ-123 "1h" --no-input

# CORRECT - Move command (no --no-input flag)
jira issue move PROJ-123 "In Progress"

# INCORRECT - May block in interactive UI
jira issue list
jira epic list
jira issue worklog add PROJ-123 "1h"  # Will prompt for comment

Installation

macOS (via Homebrew)

brew install jira-cli

Linux

Download the latest release from GitHub:

# For amd64
wget https://github.com/ankitpokhrel/jira-cli/releases/latest/download/jira_linux_amd64.tar.gz
tar -xzf jira_linux_amd64.tar.gz
sudo mv jira /usr/local/bin/

Windows

Download from the releases page or use Scoop:

scoop install jira-cli

Docker

docker run -it --rm ghcr.io/ankitpokhrel/jira-cli:latest

Other Package Managers

Jira CLI is also available via Nix and other package managers. See Repology for a full list.

Configuration

Cloud Server Setup

Generate a Jira API token at: https://id.atlassian.com/manage-profile/security/api-tokens
Export the token as an environment variable:
```
export JIRA_API_TOKEN="your-token-here"
```
Note: If environment variables are stored in ~/.envrc, you may need to source them first:
```
source ~/.envrc
```
Run jira init and select "Cloud" installation type
Provide your Jira instance URL (e.g., https://your-company.atlassian.net)

On-Premise Installation

Export authentication credentials:

export JIRA_API_TOKEN="your-token-here"

For Personal Access Token (PAT) authentication:
```
export JIRA_AUTH_TYPE="bearer"
```
Run jira init and select "Local" installation type
For non-English installations, manually configure epic.name, epic.link, and issue.types.*.handle in the config file

Authentication Methods

Jira CLI supports three authentication types:

Basic (default): Username and password or API token
Bearer (PAT): Personal Access Token authentication (requires JIRA_AUTH_TYPE=bearer)
mTLS: Client certificate authentication for on-premise installations

Multiple Project Support

Use the --config/-c flag or JIRA_CONFIG_FILE environment variable to load specific configurations:

jira issue list --config ~/.config/jira/project2.yml
# or
export JIRA_CONFIG_FILE=~/.config/jira/project2.yml
jira issue list

Configuration File

The configuration is stored in ~/.config/.jira/.config.yml. You can edit this file directly.

Common Commands

List Issues

# List issues assigned to you
jira issue list

# List issues with filters
jira issue list -a$(jira me) -s"To Do,In Progress"

# List issues in a specific project
jira issue list --project PROJ

# List with JQL query
jira issue list --jql "assignee=currentUser() AND status='In Progress'"

# Filter by time (relative dates supported)
jira issue list --created -7d    # Created in last 7 days
jira issue list --created week   # Created this week
jira issue list --updated month  # Updated this month

# Filter by priority, labels, components
jira issue list --priority High,Highest
jira issue list --label bug,urgent
jira issue list --component backend

View Issue Details

# View issue details
jira issue view PROJ-123

# View with comments
jira issue view PROJ-123 --comments 10

Create Issues

# Interactive mode
jira issue create

# Quick create with flags
jira issue create -tTask -s"Issue summary" -y10 -lbug,urgent

# Create from template
jira issue create --template

# Create with custom fields
jira issue create --custom field1=value1,field2=value2

# Create with parent epic
jira issue create -P PROJ-456

Update Issues

# Assign issue
jira issue assign PROJ-123 $(jira me)

# Assign to default assignee
jira issue assign PROJ-123 default

# Unassign
jira issue assign PROJ-123 x

# Move to different status (transition)
jira issue move PROJ-123 "In Progress"

# IMPORTANT: Status names vary by project/workflow
# If you get "invalid transition state" error, the status name is incorrect
# Common mistake: Using "Done" when the actual state is "Resolved" or "Closed"
# The error message will list available states for that issue

# Edit issue
jira issue edit PROJ-123

# Edit with specific fields
jira issue edit PROJ-123 -s"New summary" --priority High

# Remove labels (use minus prefix)
jira issue edit PROJ-123 --label -p2

Clone Issues

# Clone an issue
jira issue clone PROJ-123

# Clone with modifications
jira issue clone PROJ-123 -s"New summary" --priority High

# Clone with text replacement
jira issue clone PROJ-123 -H old:new

Link and Unlink Issues

# Link issues
jira issue link PROJ-123 PROJ-456 "Blocks"

# Unlink issues
jira issue unlink PROJ-123 PROJ-456

# Add web link
jira issue link PROJ-123 https://example.com "Documentation"

Delete Issues

# Delete an issue
jira issue delete PROJ-123

# Delete with cascade (including subtasks)
jira issue delete PROJ-123 --cascade

Comment Management

# Add comment
jira issue comment add PROJ-123 "Working on this"

# Add internal comment
jira issue comment add PROJ-123 --internal "Internal note"

# Add comment from file
jira issue comment add PROJ-123 --template comment.md

# Add comment from stdin
echo "Comment text" | jira issue comment add PROJ-123

Worklog and Time Tracking

IMPORTANT: Time tracking estimates are set using the worklog add command with the --new-estimate flag, NOT through custom fields.

# Add time tracking entry
jira issue worklog add PROJ-123 "2d 3h 30m"

# Add worklog with comment
jira issue worklog add PROJ-123 "4h" --comment "Fixed the bug"

# Set remaining estimate when logging work
jira issue worklog add PROJ-123 "1h" --new-estimate "3h"

# Set original estimate (log minimal time with full estimate remaining)
jira issue worklog add PROJ-123 "1m" --new-estimate "8h"

# Complete work and set remaining to 0
jira issue worklog add PROJ-123 "30m" --new-estimate "0m"

# Use --no-input to skip interactive comment prompt
jira issue worklog add PROJ-123 "1h" --new-estimate "2h" --no-input

# Add worklog with start time
jira issue worklog add PROJ-123 "1h 30m" --started "2022-01-01T09:30:00.000+0200" --new-estimate "0h"

Important notes for worklog:

Cannot log "0m" of time - This causes a server error. Log at least "1m" if you need to set an estimate without logging significant work
Use --new-estimate to set the remaining time estimate
The --no-input flag is supported and prevents interactive prompts for comments
Time formats: "1h", "30m", "1h 30m", "2d 3h 30m"
Time tracking cannot be set through --custom fields - you must use worklog add with --new-estimate

Search Issues

# Search with JQL
jira issue list --jql "project=PROJ AND status='In Progress' ORDER BY priority DESC"

# Common JQL examples
jira issue list --jql "assignee=currentUser() AND status!=Done"
jira issue list --jql "created >= -7d AND assignee=currentUser()"
jira issue list --jql "priority in (High, Highest) AND status='To Do'"

Epic Management

# List epics
jira epic list

# List epics in table view
jira epic list --table

# View issues in a specific epic
jira epic list PROJ-123

# Create epic
jira epic create

# Add issues to epic (up to 50 at a time)
jira epic add PROJ-123 PROJ-456 PROJ-789

# Remove issues from epic
jira epic remove PROJ-123 PROJ-456

Sprint Management

# List sprints (shows 25 most recent)
jira sprint list

# List issues in current sprint
jira sprint list --current

# List issues in previous/next sprint
jira sprint list --prev
jira sprint list --next

# Filter by sprint state
jira sprint list --state future,active

# Add issue to sprint (up to 50 at a time)
jira sprint add SPRINT-ID PROJ-123 PROJ-456

Project and Board Management

# List accessible projects
jira project list

# List boards
jira board list

# List releases/versions
jira release list

Utility Commands

# Open project or issue in browser
jira open
jira open PROJ-123

# Get current user information
jira me

# Enable shell completion
jira completion bash > /etc/bash_completion.d/jira
jira completion zsh > "${fpath[1]}/_jira"

Output Formats

Jira CLI supports multiple output formats:

# Default interactive table view
jira issue list

# Plain text (for scripting)
jira issue list --plain

# Raw JSON output
jira issue list --raw

# CSV format
jira issue list --csv

# No headers (with plain output)
jira issue list --plain --no-headers

Interactive UI Navigation

The default list view supports keyboard navigation:

Arrow keys or j/k/h/l: Navigate up/down/left/right
g/G: Jump to top/bottom
CTRL+f/b: Page down/up
v: View issue details
m: Transition/move issue to different status
ENTER: Open issue in browser
c: Copy issue URL to clipboard
CTRL+k: Copy issue key to clipboard
w or TAB: Toggle sidebar focus
CTRL+r or F5: Refresh list
?: Display help

Useful Aliases

Add these to your shell configuration for quicker access:

# List your current issues
alias jira-mine='jira issue list -a$(jira me) -s"To Do,In Progress"'

# Quick view
alias jv='jira issue view'

# List current sprint
alias jira-sprint='jira sprint list --current'

# Open issue quickly
alias jo='jira open'

Advanced Usage

Custom Views

Create custom issue views in ~/.config/jira/.config.yml:

issue:
  fields:
    - key
    - type
    - summary
    - status
    - assignee
    - priority
    - created

Custom Fields

Configure custom field mapping in ~/.config/jira/.config.yml:

custom:
  customfield_10001: Team
  customfield_10002: Story Points

Then use them in commands:

jira issue create --custom Team=Backend,Story\ Points=5

Setting Due Dates

CRITICAL DISTINCTION: Do not confuse due dates with time tracking:

Due dates (calendar dates): Set via --custom parameter (requires configuration)
Time tracking (estimates/time spent): Set via jira issue worklog add with --new-estimate flag
Never try to set time tracking fields (timeoriginalestimate, timetracking, etc.) via --custom - it will not work

IMPORTANT: The duedate field is treated as a custom field and must be explicitly configured to be visible in API responses and usable via the --custom parameter.

Configuration Required for Due Dates

Due dates require special configuration because duedate is a standard Jira field that doesn't appear by default in the Jira CLI API responses. To enable setting and viewing due dates:

Add the following to your ~/.config/jira/.config.yml:

issue:
  fields:
    custom:
      - name: duedate
        key: duedate
        schema:
          datatype: date

Then you can set due dates when creating or editing issues:

jira issue create --type Task --summary "Task summary" --custom "duedate=2024-12-31"
jira issue edit PROJ-123 --custom "duedate=2024-12-31"

Requesting Due Dates in API Responses

Without the above configuration:

The duedate field will NOT appear in jira issue list --raw output
Attempts to use --custom "duedate=..." will show a warning that the field is "not configured" and will be ignored
Due dates cannot be set or retrieved via the CLI

With the configuration:

Due dates will appear in the fields object of JSON responses from --raw output
You can set due dates using the --custom parameter
Due dates can be included in custom views

Note: This is a known limitation of the jira-cli tool. See jira-cli issue #698 for more details.

Scripting with Jira CLI

Use raw JSON output for scripting:

#!/bin/bash
# Get all high priority issues
jira issue list --jql "priority=High" --raw | jq -r '.issues[].key'

# Count issues by status
jira issue list --plain --no-headers | awk '{print $4}' | sort | uniq -c

Templates

Create markdown templates for issues and comments:

# Issue template (issue-template.md)
## Description
What needs to be done?

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

# Use template
jira issue create --template issue-template.md

Troubleshooting

Authentication Issues

# Re-initialize configuration
jira init --force

# Check current user
jira me

# Verify API token is set
echo $JIRA_API_TOKEN

Connection Issues

# Test connection
jira issue list --limit 1

# Enable debug mode
JIRA_DEBUG=1 jira issue list

Clear Cache

# Clear cached data
rm -rf ~/.config/jira/.cache

Time Tracking Errors

Error: "field not on the appropriate screen"

This occurs when trying to set time tracking via --custom fields
Solution: Use jira issue worklog add with --new-estimate instead
Time tracking fields cannot be set via the edit command

Error: "Internal server error" (500) when logging time

Usually caused by trying to log "0m" of time
Solution: Log at least "1m" - you cannot log zero time
Example: jira issue worklog add PROJ-123 "1m" --new-estimate "8h"

Warning: "field is not configured" for timeoriginalestimate/timetracking

This appears when using --custom for time tracking fields
Solution: Ignore the warning - use worklog add command instead
Do NOT try to configure these as custom fields - they're managed differently

Error: "invalid transition state" when closing issues

Status names vary by project/workflow
Common mistake: Using "Done" when the actual state is "Resolved" or "Closed"
Solution: Check the error message for available states
Or view the issue in browser: jira open PROJ-123

Resources

Notes

The Jira CLI uses the Jira REST API under the hood
API tokens are more secure than passwords and are the recommended authentication method
Most commands support --help for detailed usage information
Supports both Jira Cloud and on-premise installations
Output is converted from Atlassian Document Format to markdown for better terminal display