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:

1. Time Tracking: MUST use jira issue worklog add ISSUE "1m" --new-estimate "1h" - DO NOT use --custom for time tracking
2. Cannot log 0m: Logging "0m" causes server errors - always log at least "1m"
3. Status Names Vary: "Done" may not exist - use exact status name from error message (e.g., "Resolved", "Closed")
4. --no-input Support: Not all commands support --no-input:
   • ✓ Supported: issue edit, issue worklog add
   • ✗ Not supported: issue move, view/list commands
5. 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:

1. First try running jira commands directly (e.g., jira me --plain)
2. If authentication fails, check if JIRA_API_TOKEN is set: echo $JIRA_API_TOKEN
3. If not set, then try sourcing common environment files like ~/.envrc
4. 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

1. Generate a Jira API token at: https://id.atlassian.com/manage-profile/security/api-tokens
2. 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
   

3. Run jira init and select "Cloud" installation type
4. Provide your Jira instance URL (e.g., https://your-company.atlassian.net)

On-Premise Installation

1. Export authentication credentials:

   export JIRA_API_TOKEN="your-token-here"
   

2. For Personal Access Token (PAT) authentication:

   export JIRA_AUTH_TYPE="bearer"
   

3. Run jira init and select "Local" installation type
4. 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:

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

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

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

• Official Documentation
• JQL Guide
• Issue with installation or usage?

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